Popup

Una finestra popup visualizza il contenuto sopra gli altri elementi dell'interfaccia utente dell'app. La classe Popup nello Microsoft.UI.Xaml.Controls.Primitives spazio dei nomi è un contenitore per utilizzo generico per tale contenuto. Non ha un modello visivo predefinito, quindi è necessario fornire il contenuto, il relativo aspetto e la logica che lo apre e lo chiude.

Popup è un elemento costitutivo di basso livello. WinUI fornisce anche controlli per tipi comuni di interfaccia utente temporanea, ad esempio riquadri a comparsa, dialoghi, teaching tip e descrizioni comando. Questi controlli includono il proprio stile, posizionamento e comportamento di chiusura.

Un pulsante con etichetta

Questo è il controllo giusto?

Non usare Popup se un controllo di livello superiore rientra nel tuo scenario. Usare invece questi controlli:

Scenario CTRL
Mostrare informazioni o raccogliere input correlati a un elemento, nell'interfaccia utente che si chiude quando l'utente fa clic all'esterno. Flyout
Visualizzare un elenco di comandi o opzioni. MenuFlyout
Porre una domanda o mostrare informazioni a cui l'utente deve rispondere prima di continuare. ContentDialog
Indicare una funzionalità nuova o importante, con o senza selezionare un elemento specifico. TeachingTip
Mostra una breve descrizione di un elemento quando l'utente passa il puntatore del mouse su di esso o sposta lo stato attivo su di esso. Suggerimento

Usa un oggetto Popup quando hai bisogno di contenuti personalizzati che si sovrappongono alla tua interfaccia utente e nessuno di questi controlli soddisfa le tue esigenze. Ad esempio, è possibile usare un popup per un overlay che puoi stilizzare e posizionare manualmente.

Un popup non è modale, quindi l'utente può comunque interagire con l'interfaccia utente sottostante. Se l'utente deve rispondere prima di continuare, usare ContentDialog.

Recommendations

  • Assegnare al contenuto popup uno sfondo, un bordo e angoli arrotondati in modo da distinguersi dall'interfaccia utente sottostante. L'esempio della Gallery WinUI 3 usa le risorse AcrylicBackgroundFillColorDefaultBrush, SurfaceStrokeColorDefaultBrush e OverlayCornerRadius. Per altre info, vedi Materiale acrilico e ThemeShadow in Popup.
  • Se non si abilita light dismiss, includere un pulsante o un altro controllo che chiude il popup.
  • Mantenere il contenuto popup breve e incentrato su una singola attività.

Creare un popup

Aprire l'app Raccolta WinUI 3 e visualizzare il popup in azione

Icona della raccolta WinUI 3 L'app Raccolta WinUI 3 include esempi interattivi di controlli e funzionalità WinUI. Ottenere l'app dal Microsoft Store o esplorare il codice sorgente in GitHub.

Un popup ospita un singolo elemento, impostato come Child. Il child è in genere un pannello o un oggetto UserControl che definisce il contenuto popup. Per visualizzare il popup, impostare IsOpen su true. Per nasconderlo, impostare IsOpen su false.

Questo esempio si basa sull'esempio di WinUI 3 Gallery. Dichiara un popup accanto al pulsante che lo apre e il contenuto popup include un pulsante che chiude il popup.

<Grid HorizontalAlignment="Left" VerticalAlignment="Top">
    <Button Content="Show popup" Click="ShowPopupClicked" />
    <Popup x:Name="StandardPopup" HorizontalOffset="200" VerticalOffset="0">
        <Grid MinWidth="240"
              Padding="16"
              Background="{ThemeResource AcrylicBackgroundFillColorDefaultBrush}"
              BorderBrush="{ThemeResource SurfaceStrokeColorDefaultBrush}"
              BorderThickness="1"
              CornerRadius="{StaticResource OverlayCornerRadius}">
            <StackPanel Spacing="8">
                <TextBlock FontSize="16" Text="Simple popup" />
                <Button Content="Close" Click="ClosePopupClicked" />
            </StackPanel>
        </Grid>
    </Popup>
</Grid>

// Opens the popup if it isn't already open.
private void ShowPopupClicked(object sender, RoutedEventArgs e)
{
    if (!StandardPopup.IsOpen)
    {
        StandardPopup.IsOpen = true;
    }
}

// Closes the popup when the user clicks the Close button inside it.
private void ClosePopupClicked(object sender, RoutedEventArgs e)
{
    if (StandardPopup.IsOpen)
    {
        StandardPopup.IsOpen = false;
    }
}

Creare un popup nel codice

È anche possibile creare un popup nel codice senza aggiungerlo alla struttura ad albero visuale. Un popup dichiarato in XAML o aggiunto a un pannello nella struttura ad albero visuale ottiene XamlRoot dal relativo elemento padre. Un popup che non ha un elemento padre non ne ha uno, quindi è necessario impostarne la proprietà XamlRoot prima di aprirla.

private Popup? _popup;

private void ShowPopupFromCodeClicked(object sender, RoutedEventArgs e)
{
    _popup ??= new Popup
    {
        // PopupContent is a UserControl in your app that defines the popup content.
        Child = new PopupContent(),
        IsLightDismissEnabled = true,

        // Required because this popup isn't in the visual tree. Use the XamlRoot
        // of an element that's already loaded, such as the button that was clicked.
        XamlRoot = ((UIElement)sender).XamlRoot
    };

    _popup.IsOpen = true;
}

Important

In WinUI 3, l'apertura di un popup che non ha né un elemento padre né un XamlRoot non riesce. La proprietà null di un elemento è XamlRoot finché l'elemento non viene aggiunto alla struttura ad albero visuale attiva, quindi recupera il valore da un elemento già caricato, anziché in un costruttore di pagina. In una Window classe è possibile usare this.Content.XamlRoot. Per altre info, vedi ContentDialog e Popup.

Note

Un popup che non si trova nell'albero visivo non si riposiziona quando viene visualizzata la tastiera virtuale, quindi la tastiera può coprirlo. Se il popup contiene controlli di input di testo, ad esempio , TextBoxdichiarare il popup in XAML o aggiungerlo a un pannello nella struttura ad albero visuale.

Chiudere un popup con chiusura rapida

Per impostazione predefinita, un popup rimane aperto fino a quando il codice non imposta IsOpen su false. Impostare IsLightDismissEnabled su true per chiudere il popup quando l'utente fa clic o tocca all'esterno oppure preme il tasto ESC. Questo comportamento viene chiamato light dismiss.

Per impostazione predefinita, l'area esterna a un popup a chiusura automatica non viene oscurata. Per scurirla, impostare LightDismissOverlayMode su On. Questa proprietà non ha alcun effetto quando IsLightDismissEnabled è false.

<Popup x:Name="LightDismissPopup"
       IsLightDismissEnabled="True"
       LightDismissOverlayMode="On">
    <Border Padding="16"
            Background="{ThemeResource AcrylicBackgroundFillColorDefaultBrush}"
            BorderBrush="{ThemeResource SurfaceStrokeColorDefaultBrush}"
            BorderThickness="1"
            CornerRadius="{StaticResource OverlayCornerRadius}">
        <TextBlock Text="Click outside this popup or press Esc to close it." />
    </Border>
</Popup>

Posizionare un popup

È possibile posizionare un popup usando gli offset o rispetto a un altro elemento.

Usare gli offset

HorizontalOffset e VerticalOffset impostano la posizione del popup, in pixel. Il punto da cui vengono misurati gli offset dipende dal fatto che il popup abbia un elemento padre:

  • Un popup nella struttura ad albero visuale viene spostato dalla propria posizione nel layout del relativo elemento padre. Ad esempio, in un layout verticale StackPanel, quella posizione si trova sotto gli elementi che precedono il popup. Nel primo esempio, il popup condivide una singola cella Grid con il pulsante, quindi viene visualizzato 200 pixel a destra dell'angolo superiore sinistro di Grid.
  • Un popup che non ha un elemento padre, ad esempio uno creato nel codice, viene scostato dall'angolo superiore sinistro della radice XAML, che in genere è l'area di contenuto della finestra dell'app.

Posizionare un popup accanto a un elemento

Per visualizzare un popup accanto a un elemento specifico, impostare PlacementTarget su tale elemento. Quindi impostare DesiredPlacement su un valore PopupPlacementMode diverso da Auto, ad esempio Bottom o RightEdgeAlignedTop.

Quando si apre il popup, il framework lo posiziona rispetto all'elemento di destinazione. Se il popup non rientra nella posizione preferita, il framework lo sposta sul lato opposto dell'elemento di destinazione. HorizontalOffset e VerticalOffset si applicano ancora e spostano il popup dalla posizione calcolata.

ActualPlacement indica dove viene visualizzato il popup. L'evento ActualPlacementChanged si verifica quando il valore cambia mentre il popup è aperto.

<StackPanel Spacing="8">
    <Button x:Name="DetailsButton" Content="Show details" Click="ShowDetailsClicked" />
    <TextBlock x:Name="PlacementStatus" />
    <Popup x:Name="DetailsPopup"
           PlacementTarget="{x:Bind DetailsButton}"
           DesiredPlacement="BottomEdgeAlignedLeft"
           IsLightDismissEnabled="True"
           ActualPlacementChanged="DetailsPopup_ActualPlacementChanged">
        <Border Padding="16"
                Background="{ThemeResource AcrylicBackgroundFillColorDefaultBrush}"
                BorderBrush="{ThemeResource SurfaceStrokeColorDefaultBrush}"
                BorderThickness="1"
                CornerRadius="{StaticResource OverlayCornerRadius}">
            <TextBlock Text="This popup appears below the button when there's room." />
        </Border>
    </Popup>
</StackPanel>

private void ShowDetailsClicked(object sender, RoutedEventArgs e)
{
    DetailsPopup.IsOpen = true;
}

private void DetailsPopup_ActualPlacementChanged(object sender, object e)
{
    // ActualPlacement differs from DesiredPlacement when the popup
    // doesn't fit in the preferred position.
    PlacementStatus.Text = $"Actual placement: {DetailsPopup.ActualPlacement}";
}

Visualizzare un popup all'esterno della finestra dell'app

Per impostazione predefinita, un popup è vincolato ai limiti della radice XAML, che in genere è l'area del contenuto della finestra dell'app. A partire da SDK per app di Windows 1.4, è possibile impostare ShouldConstrainToRootBounds su false per consentire al popup di estendersi oltre la finestra. Ad esempio, è possibile eseguire questa operazione quando il popup è più grande di una piccola finestra.

Impostare ShouldConstrainToRootBounds prima di aprire il popup per la prima volta. Non è possibile modificarlo dopo l'apertura del popup.

<Popup x:Name="UnconstrainedPopup" ShouldConstrainToRootBounds="False">
    <!-- Popup content -->
</Popup>

Anima un popup

Per animare il contenuto popup quando viene visualizzato, aggiungere una transizione all'insieme ChildTransitions . PopupThemeTransition fornisce l'animazione per l'interfaccia utente popup, ad esempio il contenuto simile alla descrizione comando, così come viene visualizzato.

<Popup x:Name="AnimatedPopup" IsLightDismissEnabled="True">
    <Popup.ChildTransitions>
        <TransitionCollection>
            <PopupThemeTransition />
        </TransitionCollection>
    </Popup.ChildTransitions>
    <Border Padding="16"
            Background="{ThemeResource AcrylicBackgroundFillColorDefaultBrush}"
            BorderBrush="{ThemeResource SurfaceStrokeColorDefaultBrush}"
            BorderThickness="1"
            CornerRadius="{StaticResource OverlayCornerRadius}">
        <TextBlock Text="This content animates when the popup opens." />
    </Border>
</Popup>

Per controllare invece le animazioni di visualizzazione e nascondimento da uno storyboard, usare PopInThemeAnimation e PopOutThemeAnimation. Per altre info, vedi Mostra/nascondi popup.

Reagire all'apertura o alla chiusura di un popup

L'evento Opened si verifica quando IsOpen è impostato su true. L'evento Closed si verifica quando IsOpen è impostato su false, incluso quando il popup si chiude tramite chiusura al clic all'esterno. Usare Closed per le operazioni che devono avvenire indipendentemente da come si chiude il popup. Ad esempio, l'esempio della raccolta WinUI 3 usa Closed per riabilitare un'impostazione che disabilita mentre il popup è aperto.

Entrambi gli eventi usano EventHandler<object>, quindi i gestori accettano un object mittente e un object argomento evento.

<StackPanel Spacing="8">
    <TextBlock x:Name="StatusText" />
    <Popup x:Name="StatusPopup"
           IsLightDismissEnabled="True"
           Opened="StatusPopup_Opened"
           Closed="StatusPopup_Closed">
        <!-- Popup content -->
    </Popup>
</StackPanel>

private void StatusPopup_Opened(object sender, object e)
{
    StatusText.Text = "The popup is open.";
}

private void StatusPopup_Closed(object sender, object e)
{
    // Closed occurs for every close, including light dismiss.
    StatusText.Text = "The popup is closed.";
}

Tastiera, focus e accessibilità

  • Quando il dismiss leggero è abilitato, l'apertura del popup sposta il focus al suo interno e la chiusura del popup restituisce il focus all'elemento che lo aveva in precedenza. L'utente può anche premere ESC per chiudere il popup.
  • Quando light dismiss non è abilitato, il popup non sposta lo stato attivo all'apertura. Spostare lo stato attivo su un elemento nel popup dopo averlo aperto, includere un pulsante Chiudi che gli utenti della tastiera possono raggiungere e restituire lo stato attivo all'elemento che ha aperto il popup dopo la chiusura.
  • Un popup non genera eventi indirizzati, ad esempio KeyDown e PointerPressed. Per gestire questi eventi, collegare invece i gestori all'elemento figlio del popup.
  • Assicurarsi che ogni elemento interattivo nel popup abbia un nome accessibile. Per altre info, vedi Accessibilità da tastiera ed Esporre informazioni di accessibilità di base.
  • Ultimo aggiornamento: