Fenêtre contextuelle

Les fenêtres contextuelles (« Popup ») sont un moyen très courant de présenter des informations à un utilisateur en rapport avec la tâche qu’il exécute. 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 disposition et à l’apparence.

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

Création d’une fenêtre contextuelle

Il est possible de créer un Popup en XAML ou en C# :

XAML

Y compris l’espace de noms XAML

Pour utiliser le kit de ressources dans XAML, le xmlns suivant doit être ajouté à votre page ou à votre affichage :

xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"

Il en résulte ce qui suit :

<ContentPage
    x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml">

</ContentPage>

Serait modifié pour inclure le xmlns de la manière suivante :

<ContentPage
    x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit">

</ContentPage>

Définition de votre fenêtre contextuelle

Notez que si un Popup est créé en XAML, il doit également disposer d’un fichier code-behind C#. Pour savoir pourquoi cela est nécessaire, reportez-vous à cette page de documentation .NET MAUI.

Le moyen le plus simple de créer un Popup est d’ajouter un .NET MAUI ContentView (XAML) à votre projet et de modifier chacun des fichiers comme suit :

<toolkit:Popup xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
               xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
               xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
               x:Class="MyProject.SimplePopup">

    <VerticalStackLayout>
        <Label Text="This is a very important message!" />
    </VerticalStackLayout>
    
</toolkit:Popup>

public partial class SimplePopup : Popup
{
    public SimplePopup()
    {
        InitializeComponent();
    }
}

C#

using CommunityToolkit.Maui.Views;

var popup = new Popup
{
    Content = new VerticalStackLayout
    {
        Children = 
        {
            new Label
            {
                Text = "This is a very important message!"
            }
        }
    }
};

Présentation d’une fenêtre contextuelle

Une fois que le Popup a été créé, il peut ensuite être présenté à l’aide de nos méthodes d’extension Popup ou via l’implémentation IPopupService de ce kit de ressources.

using CommunityToolkit.Maui.Views;

public class MyPage : ContentPage
{
    public void DisplayPopup()
    {
        var popup = new SimplePopup();

        this.ShowPopup(popup);
    }
}

Fermeture d’une fenêtre contextuelle

Il existe deux façons différentes de fermer un Popup : par programmation ou en appuyant à l’extérieur de la fenêtre contextuelle.

Fermeture d’une fenêtre contextuelle par programmation

Pour fermer un Popup, un développeur doit appeler Close ou CloseAsync sur le Popup lui-même. Cela se fait généralement en répondant à un appui sur un bouton effectué par un utilisateur.

Nous pouvons améliorer l’exemple XAML précédent en ajoutant un OKButton :

<toolkit:Popup xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
               xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
               xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
               x:Class="MyProject.SimplePopup">

    <VerticalStackLayout>
        <Label Text="This is a very important message!" />
        <Button Text="OK" 
                Clicked="OnOKButtonClicked" />
    </VerticalStackLayout>
    
</toolkit:Popup>

Dans le gestionnaire d’événements obtenu, nous appelons Close, ce qui a pour effet de fermer le Popup par programmation.

public partial class MySimplePopup : Popup
{
    // ...

    void OnOKButtonClicked(object? sender, EventArgs e) => Close();
}

Dans le gestionnaire d’événements obtenu, nous appelons CloseAsync, ce qui ferme par programmation le Popup. L’appelant peut alors utiliser await pour attendre la méthode, le temps que le système d’exploitation ait supprimé le Popup de l’écran.

public partial class MySimplePopup : Popup
{
    // ...

    async void OnOKButtonClicked(object? sender, EventArgs e) 
    {
        var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));

         await CloseAsync(token: cts.Token);
         await Toast.Make("Popup Dismissed By Button").Show();
    }
}

Appui à l’extérieur 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é CanBeDismissedByTappingOutsideOfPopup. En définissant cette propriété sur false, vous empêcherez un utilisateur de supprimer le Popup via un appui à l’extérieur de celui-ci.

Retour d’un résultat

Il arrivera assez souvent qu’un développeur cherche à obtenir une réponse de ses utilisateurs. La vue Popup permet aux développeurs de retourner un résultat qui peut être attendu et traité.

Nous pouvons améliorer notre exemple XAML d’origine pour montrer comment faire cela :

XAML

En ajoutant 2 nouveaux boutons au code XAML :

<toolkit:Popup xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
               xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
               xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
               x:Class="MyProject.SimplePopup">

    <VerticalStackLayout>
        <Label Text="This is a very important message! Do you agree?" />
        <Button Text="Yes" 
                Clicked="OnYesButtonClicked" />
        <Button Text="No"
                Clicked="OnNoButtonClicked" />
    </VerticalStackLayout>
    
</toolkit:Popup>

Puis en ajoutant les gestionnaires d’événements suivants dans le code C# :

async void OnYesButtonClicked(object? sender, EventArgs e)
{
    var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
    await CloseAsync(true, cts.Token);
}

async void OnNoButtonClicked(object? sender, EventArgs e)
{
    var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
    await CloseAsync(false, cts.Token);
}

La méthode Close permet de fournir une valeur object ; il s’agira de la valeur de retour résultante. Pour attendre le résultat, la méthode ShowPopupAsync doit être utilisée comme suit :

using CommunityToolkit.Maui.Views;

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

        var result = await this.ShowPopupAsync(popup, CancellationToken.None);

        if (result is bool boolResult)
        {
            if (boolResult)
            {
                // Yes was tapped
            }
            else
            {
                // No was tapped
            }
        }
    }
}

Style

La classe Popup permet l’utilisation de Styles .NET MAUI pour faciliter le partage de paramètres visuels communs entre plusieurs fenêtres contextuelles.

L’exemple suivant montre comment définir un style qui s’applique à l’exemple SimplePopup de la section précédente.

<toolkit:Popup xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
               xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
               xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
               xmlns:popups="clr-namespace:CommunityToolkit.Maui.Sample.Views.Popups"
               x:Class="MyProject.SimplePopup">

    <toolkit:Popup.Resources>
        <Style TargetType="{x:Type popups:SimplePopup}">
            <Setter Property="Size" Value="100,200" />
            <Setter Property="Color" Value="Green" />
            <Setter Property="HorizontalOptions" Value="Center" />
            <Setter Property="VerticalOptions" Value="Start" />
            <Setter Property="CanBeDismissedByTappingOutsideOfPopup" Value="True" />
        </Style>
    </toolkit:Popup.Resources>

    <VerticalStackLayout>
        <Label Text="This is a very important message! Do you agree?" />
        <Button Text="Yes" 
                Clicked="OnYesButtonClicked" />
        <Button Text="No"
                Clicked="OnNoButtonClicked" />
    </VerticalStackLayout>
    
</toolkit:Popup>

Propriétés

Événements

Exemples

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

API

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