Popup

Une fenêtre contextuelle affiche du contenu par-dessus le reste de l’interface utilisateur de votre application. La classe Popup dans l’espace Microsoft.UI.Xaml.Controls.Primitives de noms est un conteneur à usage général pour ce contenu. Il n’a pas de modèle visuel par défaut. Vous fournissez donc le contenu, son apparence et la logique qui permet de l’ouvrir et de la fermer.

Popup est un bloc de construction de bas niveau. WinUI fournit également des contrôles pour les types courants d’interface utilisateur temporaire, tels que les menus volants, les boîtes de dialogue, les info-bulles pédagogiques et les info-bulles. Ces contrôles incluent leur propre style, leur placement et leur comportement de fermeture.

Est-ce le contrôle approprié ?

N’utilisez pas un Popup si un contrôle de niveau supérieur convient à votre scénario. Utilisez ces contrôles à la place :

Utilisez un Popup lorsque vous avez besoin de contenu personnalisé qui flotte au-dessus de votre interface utilisateur et qu’aucun de ces contrôles ne répond à vos besoins. Par exemple, vous pouvez utiliser une fenêtre contextuelle pour une superposition que vous mettez en forme et positionnez vous-même.

Une fenêtre contextuelle n’est pas modale, de sorte que l’utilisateur peut toujours interagir avec l’interface utilisateur derrière elle. Si l’utilisateur doit répondre avant de continuer, utilisez un ContentDialog.

Recommendations

• Donnez au contenu de la fenêtre contextuelle un arrière-plan, une bordure et des angles arrondis afin qu’il se distingue de l’interface utilisateur derrière lui. L’exemple de la galerie WinUI 3 utilise les ressources OverlayCornerRadius, SurfaceStrokeColorDefaultBrush et AcrylicBackgroundFillColorDefaultBrush. Pour plus d’informations, consultez matériau acrylique et ThemeShadow dans les Popups.
• Si vous n’activez pas l’abandon interactif, incluez un bouton ou une autre commande qui ferme la fenêtre contextuelle.
• Conservez le contenu de la fenêtre contextuelle bref et concentrez-vous sur une tâche unique.

Créer une fenêtre contextuelle

L’application Galerie WinUI 3 inclut des exemples interactifs de contrôles et de fonctionnalités WinUI. Obtenez l’application à partir du Microsoft Store ou parcourez le code source sur GitHub.

Une fenêtre contextuelle héberge un seul élément, que vous définissez comme Child. L’enfant est généralement un panneau ou un UserControl qui définit le contenu de la fenêtre contextuelle. Pour afficher la fenêtre contextuelle, définissez IsOpen sur true. Pour le masquer, définissez IsOpen sur false.

Cet exemple est basé sur l’exemple de galerie WinUI 3. Il déclare une fenêtre contextuelle en regard du bouton qui l’ouvre, et le contenu contextuel inclut un bouton qui ferme la fenêtre contextuelle.

<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;
    }
}

Créer une fenêtre contextuelle dans le code

Vous pouvez également créer une fenêtre contextuelle dans le code sans l’ajouter à l’arborescence visuelle. Une fenêtre contextuelle que vous déclarez en XAML ou que vous ajoutez à un panneau dans l’arborescence visuelle obtient son XamlRoot à partir de son élément parent. Une fenêtre contextuelle qui n’a pas de parent n’en a pas, vous devez donc définir sa propriété XamlRoot avant de l’ouvrir.

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;
}

Fermer une fenêtre contextuelle avec abandon interactif

Par défaut, une fenêtre contextuelle reste ouverte jusqu’à ce que votre code définisse IsOpen sur false. Définissez IsLightDismissEnabled sur true pour fermer la fenêtre contextuelle lorsque l’utilisateur clique ou appuie en dehors de celle-ci, ou appuie sur la touche Échap. Ce comportement est appelé abandon interactif.

Par défaut, la zone en dehors d’une fenêtre contextuelle à fermeture en cliquant à l’extérieur n’est pas assombrie. Pour l’assombrir, définissez LightDismissOverlayMode sur On. Cette propriété n’a aucun effet quand IsLightDismissEnabled est 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>

Positionner une fenêtre contextuelle

Vous pouvez positionner une fenêtre contextuelle à l’aide de décalages ou par rapport à un autre élément.

Utiliser des décalages

HorizontalOffset et VerticalOffset définissent la position de la fenêtre contextuelle, en pixels. Le point à partir duquel les décalages sont mesurés dépend du fait que la fenêtre contextuelle a un parent :

• Une fenêtre contextuelle dans l’arborescence visuelle est décalée par rapport à sa propre position dans la disposition de son parent. Par exemple, dans un StackPanel vertical, cette position se trouve sous les éléments qui viennent avant la fenêtre contextuelle. Dans le premier exemple, la fenêtre contextuelle partage une seule cellule Grid avec le bouton, de sorte qu’elle apparaît à 200 pixels à droite du coin supérieur gauche du Grid.
• Une fenêtre contextuelle qui n’a aucun parent, par exemple celle que vous créez dans le code, est décalée à partir du coin supérieur gauche de sa racine XAML, qui est généralement la zone de contenu de la fenêtre de votre application.

Placer une fenêtre contextuelle en regard d’un élément

Pour afficher une fenêtre contextuelle en regard d’un élément spécifique, définissez PlacementTarget sur cet élément. Définissez ensuite DesiredPlacement sur une valeur de type PopupPlacementMode autre que Auto, telle que Bottom ou RightEdgeAlignedTop.

Lorsque la fenêtre contextuelle s’ouvre, l’infrastructure la positionne par rapport à l’élément cible. Si la fenêtre contextuelle ne tient pas dans la position préférée, le framework la déplace vers le côté opposé de la cible. HorizontalOffset et VerticalOffset s’appliquent toujours, et déplacent la fenêtre contextuelle à partir de la position calculée.

ActualPlacement indique où la fenêtre contextuelle s’affiche. L’événement ActualPlacementChanged se produit lorsque cette valeur change tant que la fenêtre contextuelle est ouverte.

<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}";
}

Afficher une fenêtre contextuelle en dehors de la fenêtre de l’application

Par défaut, une fenêtre contextuelle est limitée aux limites de sa racine XAML, qui est généralement la zone de contenu de votre fenêtre d’application. À compter de SDK d'application Windows 1.4, vous pouvez définir ShouldConstrainToRootBounds sur false pour permettre à la fenêtre contextuelle de s’étendre au-delà de la fenêtre. Par exemple, vous pouvez le faire lorsque la fenêtre contextuelle est plus grande qu’une petite fenêtre.

Définissez ShouldConstrainToRootBounds avant d’ouvrir la fenêtre contextuelle pour la première fois. Vous ne pouvez pas le modifier une fois la fenêtre contextuelle ouverte.

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

Animer une fenêtre contextuelle

Pour animer le contenu contextuel lorsqu’il apparaît, ajoutez une transition à la collection ChildTransitions . PopupThemeTransition fournit l’animation de l’interface utilisateur surgissante, telle que le contenu de type info-bulle, tel qu’il apparaît.

<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>

Pour contrôler les animations d’affichage et de masquage à partir d’un storyboard à la place, utilisez PopInThemeAnimation et PopOutThemeAnimation. Pour plus d’informations, voir Afficher/masquer la fenêtre contextuelle.

Répondre lorsqu’une fenêtre contextuelle s’ouvre ou se ferme

L’événement Ouvert se produit lorsque IsOpen est défini sur true. L’événement Fermé se produit lorsque IsOpen est défini sur false, y compris lorsque la fenêtre contextuelle se ferme via la fermeture par clic à l’extérieur. Utilisez Closed pour les tâches à exécuter, quelle que soit la façon dont la fenêtre contextuelle se ferme. Par exemple, l’exemple de galerie WinUI 3 utilise Closed pour réactiver un paramètre qu’il désactive pendant l’ouverture de la fenêtre contextuelle.

Les deux événements utilisent EventHandler<object>, de sorte que vos gestionnaires acceptent un object expéditeur et un argument d’événement object .

<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.";
}

Clavier, focus et accessibilité

• Lorsque la fermeture par clic à l’extérieur est activée, l’ouverture de la fenêtre contextuelle déplace le focus sur celle-ci et la fermeture de la fenêtre contextuelle renvoie le focus sur l’élément qui avait le focus avant. L’utilisateur peut également appuyer sur Échap pour fermer la fenêtre contextuelle.
• Lorsque la fermeture par clic à l’extérieur n’est pas activée, la fenêtre contextuelle ne déplace pas le focus lorsqu’elle s’ouvre. Déplacez le focus sur un élément dans la fenêtre contextuelle après l’avoir ouvert, incluez un bouton Fermer que les utilisateurs du clavier peuvent atteindre et revenez au focus sur l’élément qui a ouvert la fenêtre contextuelle une fois qu’elle est fermée.
• Une fenêtre contextuelle ne déclenche pas d’événements routés, tels que KeyDown et PointerPressed. Pour gérer ces événements, attachez les gestionnaires à l’élément enfant de la fenêtre contextuelle à la place.
• Assurez-vous que chaque élément interactif dans la fenêtre contextuelle a un nom accessible. Pour plus d’informations, consultez Accessibilité du clavier et Exposer les informations d’accessibilité de base.

Articles connexes

• Boîtes de dialogue et panneaux déroulants
• Menus volants
• Contrôles de boîte de dialogue
• Conseil d’enseignement
• Info-bulles
• Ombres dans les applications Windows
• Classe de fenêtre contextuelle