Fenêtre contextuelle

Les fenêtres contextuelles sont un moyen courant de présenter des informations à un utilisateur qui se rapporte à sa tâche actuelle. Si les systèmes d’exploitation offrent un moyen d’afficher un message et d’exiger une réponse de l’utilisateur, ces alertes sont généralement restrictives quant au contenu qu’un développeur peut fournir, à la mise en page et à l’apparence.

Note

Si vous souhaitez présenter quelque chose de plus subtil à l’utilisateur, examinez nos options Toast et Snackbar.

La vue Popup permet aux développeurs de créer leur propre interface utilisateur personnalisée et de la présenter à leurs utilisateurs.

.NET MAUI Community Toolkit fournit 2 approches pour créer une Popup qui peut être affichée dans une application .NET MAUI. Ces approches dépendent du cas d’usage. Cette page se concentre sur la forme la plus simple de Popup - simplement afficher une superposition dans une application. Pour une approche plus avancée, permettant de retourner un résultat à partir du Popup, reportez-vous à Popup - Retour d’un résultat.

Affichage d’une fenêtre contextuelle

Le Kit de ressources de la communauté .NET MAUI propose plusieurs approches pour afficher une Popup dans une application .NET MAUI.

1. Dans une ContentPage, appelez la méthode d’extension this.ShowPopupAsync(), en passant une View à afficher dans la fenêtre contextuelle
   • Note: Pour personnaliser davantage une fenêtre contextuelle, reportez-vous à la documentation PopupOptions.
2. Renvoi d’un résultat depuis la Popup
   • Reportez-vous à la documentation Fenêtre contextuelle - Renvoi d’un résultat.
3. Utilisation du PopupService
   • Reportez-vous à la documentation de PopupService.

La documentation ci-dessous illustre la façon la plus simple d’afficher une fenêtre contextuelle à l’aide de la méthode d’extension .ShowPopupAsync() . Cette méthode retourne un Task<IPopupResult> qui se termine lorsque la fenêtre contextuelle se ferme. Les PopupOptions données fournies sont facultatives.

public class MainPage : ContentPage
{
    // ...

    async void DisplayPopupButtonClicked(object? sender, EventArgs e)
    {
        await this.ShowPopupAsync(new Label
        {
            Text = "This is a very important message!"
        }, new PopupOptions
        {
            CanBeDismissedByTappingOutsideOfPopup = false,
            Shape = new RoundRectangle
            {
                CornerRadius = new CornerRadius(20, 20, 20, 20),
                StrokeThickness = 2,
                Stroke = Colors.LightGray
            }
        })

        /**** Alternatively, Shell.Current can be used to display a Popup

        await Shell.Current.ShowPopupAsync(new Label
        {
            Text = "This is a very important message!"
        }, new PopupOptions
        {
            CanBeDismissedByTappingOutsideOfPopup = false,
            Shape = new RoundRectangle
            {
                CornerRadius = new CornerRadius(20, 20, 20, 20),
                StrokeThickness = 2,
                Stroke = Colors.LightGray
            }
        })
        ****/
    }
}

Vous pouvez également créer un Popup en XAML ou en C# et le transmettre à ShowPopupAsync().

Création d’une fenêtre contextuelle en XAML

Le moyen le plus simple de créer un Popup est d’ajouter un nouveau .NET MAUI ContentView (XAML) à votre projet. Cela crée 2 fichiers : un fichier *.xaml et un fichier *.xaml.cs .

Remplacez le contenu de *.xaml par les éléments suivants :

<ContentView
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    x:Class="MyProject.SimplePopup"
    Padding="10">

    <Label Text="This is a very important message!" />
    
</ContentView>

Les valeurs par défaut de HorizontalOptions et VerticalOptions entraîneront l’affichage de la Popup au centre de la page qu’elle superpose.

Une fenêtre contextuelle présente une valeur par défaut Padding de 15. Pour améliorer l’apparence de SimplePopup, une valeur de 10 a été ajoutée à Padding.

Présentation d’une fenêtre contextuelle créée en XAML

Une fois le Popup créé dans XAML, il peut ensuite être présenté via l’utilisation des méthodes d’extension Popup utilisées sur un Page, Shell ou un INavigation, ou par le biais de l’implémentation IPopupService de ce kit de ressources.

L’exemple suivant montre comment instancier et afficher le SimplePopup créé dans l’exemple précédent via une méthode d’extension sur un ContentPage.

using CommunityToolkit.Maui.Views;

public class MyPage : ContentPage
{
    public async Task DisplayPopup(CancellationToken token)
    {
        var popup = new SimplePopup();

        await this.ShowPopupAsync(popup, PopupOptions.Empty, token);
    }
}

Fermeture d’une fenêtre contextuelle

Il existe deux façons différentes de fermer un Popup.

1. Une fenêtre contextuelle peut être fermée par programmation
2. Une fenêtre contextuelle peut être fermée lorsqu’un utilisateur appuie en dehors de la fenêtre contextuelle
   • Note Pour empêcher la fermeture d'une fenêtre contextuelle lorsqu'un utilisateur appuie à l'extérieur de celle-ci, définissez PopupOptions.CanBeDismissedByTappingOutsideOfPopup sur false

1. Fermeture par programmation d’une fenêtre contextuelle

Il existe trois options pour fermer un Popup programme de manière programmatique :

1. Dans un ContentPage, utilisez la méthode d’extension this.ClosePopupAsync()
2. Dans une application utilisant Shell, utilisez la Shell.Current.ClosePopupAsync() méthode d’extension
3. Utiliser le PopupService
   • Reportez-vous à la documentation de PopupService.

Dans l’exemple ci-dessous, nous montrons comment utiliser this.ClosePopupAsync() dans un ContentPage. Pour savoir comment utiliser PopupService pour fermer une fenêtre contextuelle, reportez-vous à la documentation PopupService.

using CommunityToolkit.Maui.Views;

public class MyPage : ContentPage
{
    public async Task DisplayAutomaticallyClosingPopup(Timespan displayTimeSpan, CancellationToken token)
    {
        var popup = new SimplePopup();

        // This Popup is closed programmatically after 2 seconds
        this.ShowPopup(popup, new PopupOptions
        {
            CanBeDismissedByTappingOutsideOfPopup = false
        });

        await Task.Delay(TimeSpan.FromSeconds(displayTimeSpan), token);

        await this.ClosePopupAsync(token);

        /**** Alternatively, Shell.Current can be used to close a Popup
        Shell.Current.ShowPopup(popup, new PopupOptions
        {
            CanBeDismissedByTappingOutsideOfPopup = false
        });

        await Task.Delay(TimeSpan.FromSeconds(displayTimeSpan), token);

        await Shell.Current.ClosePopupAsync(token);
        ***/

    }
}

2. Appuyer en dehors de la fenêtre contextuelle

Par défaut, un utilisateur peut appuyer à l’extérieur du Popup pour le supprimer. Cela peut être contrôlé via la propriété PopupOptions.CanBeDismissedByTappingOutsideOfPopup. En définissant cette propriété sur false, vous empêchez l’utilisateur de supprimer le Popup en appuyant à l’extérieur de la vue. Pour plus d’informations, consultez PopupOptions .

Options de Popup

Les PageOverlayColor, Shape et Shadow peuvent tous être personnalisés pour la fenêtre contextuelle. Pour plus d’informations, consultez PopupOptions .

Définition des valeurs par défaut des fenêtres pop-up

Pour remplacer les valeurs par défaut pour chaque Popup dans votre application, vous pouvez appeler .SetPopupDefaults() et .SetPopupOptionsDefaults() lors de l’initialisation de l'outil communautaire .NET MAUI.

La DefaultPopupSettings valeur fournie sera appliquée comme valeur par défaut pour chaque Popup dans votre application, et le DefaultPopupOptionsSettings sera appliqué comme valeur par défaut pour PopupOptions chaque fois que .ShowPopup() est appelé.

.UseMauiCommunityToolkit(static options =>
{
  options.SetPopupDefaults(new DefaultPopupSettings
  {
	  CanBeDismissedByTappingOutsideOfPopup = true,
	  BackgroundColor = Colors.Orange,
	  HorizontalOptions = LayoutOptions.End,
	  VerticalOptions = LayoutOptions.Start,
	  Margin = 72,
	  Padding = 4
  });
  options.SetPopupOptionsDefaults(new DefaultPopupOptionsSettings
  {
	  CanBeDismissedByTappingOutsideOfPopup = true,
	  OnTappingOutsideOfPopup = async () => await Toast.Make("Popup Dismissed").Show(CancellationToken.None),
	  PageOverlayColor = Colors.Orange,
	  Shadow = null,
	  Shape = null
  });
})

Événements

La Popup classe fournit les événements suivants auxquels on peut s'abonner.

événement	Descriptif
Closed	Se produit suite à la fermeture du Popup.
Opened	Se produit à l’ouverture du Popup.

Exemples

Vous trouverez un exemple d’utilisation de cette fonctionnalité dans l’exemple d’application du toolkit de la communauté .NET MAUI.

API (Interface de Programmation d'Applications)

Vous pouvez trouver le code source dePopup sur le référentiel du kit de ressources de la communauté .NET MAUI sur GitHub.

Ressources additionnelles

• IPopupService
• Popup - Renvoi d’un résultat
• PopupOptions - Personnalisation d’un comportement et d’une Popup apparence
• Popup - Combinaison des fonctionnalités de Popup pour fournir un exemple complet