Popup

I popup sono un modo molto comune per presentare informazioni a un utente correlato all'attività corrente. I sistemi operativi offrono un modo per visualizzare un messaggio e richiedere una risposta dall'utente, questi avvisi sono in genere restrittivi in termini di contenuto che uno sviluppatore può fornire e anche il layout e l'aspetto.

Nota

Se vuoi presentare qualcosa all'utente che è più sottile, poi checkout le nostre opzioni Toast e Snackbar .

La Popup visualizzazione consente agli sviluppatori di creare un'interfaccia utente personalizzata e presentarla agli utenti.

Creazione di un popup

Un Popup oggetto può essere creato in XAML o C#:

XAML

Inclusione dello spazio dei nomi XAML

Per usare il toolkit in XAML, è necessario aggiungere le informazioni seguenti xmlns nella pagina o nella visualizzazione:

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

Di conseguenza:

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

Verrà modificato in modo da includere l'oggetto xmlns come indicato di seguito:

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

Definizione del popup

Si noti che se un oggetto Popup viene creato in XAML deve avere anche un file code-behind C#. Per comprendere il motivo per cui è necessario, vedere questa pagina della documentazione di .NET MAUI.

Il modo più semplice per creare un Popup oggetto consiste nell'aggiungere un nuovo .NET MAUI ContentView (XAML) al progetto e quindi modificare ognuno dei file nel modo seguente:

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

Importante

Se il file code-behind non viene creato insieme alla chiamata a InitializeComponent , verrà generata un'eccezione quando si tenta di visualizzare Popup.

C#

using CommunityToolkit.Maui.Views;

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

Presentazione di un popup

Popup Dopo averla compilata, può essere presentata tramite l'uso dei metodi di Popup estensione o tramite l'implementazione IPopupService di questo toolkit.

Importante

Un Popup oggetto può essere visualizzato solo da un oggetto o da un'implementazione Page che eredita da Page.

using CommunityToolkit.Maui.Views;

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

        this.ShowPopup(popup);
    }
}

Chiusura di un popup

Esistono due modi diversi in cui un oggetto Popup può essere chiuso, a livello di codice o toccando all'esterno del popup.

Chiusura a livello di codice di un popup

Per chiudere uno Popup sviluppatore deve chiamare Close o CloseAsync su Popup se stesso. Questa operazione viene in genere eseguita rispondendo a una pressione di un pulsante da un utente.

È possibile migliorare l'esempio XAML precedente aggiungendo 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>

Nel gestore eventi risultante chiamato Close, questo chiuderà a livello di codice .Popup

Nota

Close() è un metodo fire-and-forget. Verrà completato e tornerà al thread chiamante prima che il sistema operativo abbia ignorato dalla Popup schermata. Se è necessario sospendere l'esecuzione del codice fino a quando il sistema operativo non ha ignorato dalla Popup schermata, usare invece CloseAsync().

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

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

Nel gestore eventi risultante chiamato CloseAsync, questo chiuderà a livello di codice il Popup che consente al chiamante al metodo fino a await quando il sistema operativo non ha ignorato dalla Popup schermata.

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

Toccando all'esterno del popup

Per impostazione predefinita, un utente può toccare all'esterno Popup di per ignorarlo. Questo controllo può essere controllato tramite l'uso della CanBeDismissedByTappingOutsideOfPopup proprietà . L'impostazione di questa proprietà su false impedirà a un utente di ignorare l'oggetto Popup toccando al di fuori di esso.

Restituzione di un risultato

Uno sviluppatore cercherà spesso una risposta dall'utente, la Popup visualizzazione consente agli sviluppatori di restituire un risultato che può essere atteso e agito su.

È possibile migliorare l'esempio XAML originale per mostrare come eseguire questa operazione:

XAML

Aggiungendo 2 nuovi pulsanti al codice 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>

Aggiungere quindi i gestori eventi seguenti in 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);
}

Il Close metodo consente di specificare un object valore, ovvero il valore restituito risultante. Per attendere il risultato, è necessario usare il ShowPopupAsync metodo come segue:

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

Nota

Per gestire il tocco all'esterno di un Popup oggetto quando si attende anche il risultato, è possibile modificare il valore restituito tramite la ResultWhenUserTapsOutsideOfPopup proprietà .

Applicazione stile in corso

La Popup classe consente l'uso di stili MAUI .NET per semplificare la condivisione delle impostazioni visive comuni tra più popup.

Nell'esempio seguente viene illustrato come definire uno stile applicabile all'esempio SimplePopup della sezione precedente.

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

Nota

Quando si crea una StylePopup destinazione e si vuole applicarla a popup personalizzati come l'esempio SimplePopup , assicurarsi di impostare la ApplyToDerivedTypes proprietà nella Style definizione.

Proprietà

Proprietà	Type	Descrizione
Anchor	View	Ottiene o imposta l'ancoraggio View . L'ancoraggio è il punto in cui il popup eseguirà il rendering più vicino. Quando un ancoraggio è configurato, il popup verrà visualizzato centrato su tale controllo o il più vicino possibile.
CanBeDismissedByTappingOutsideOfPopup	bool	Ottiene o imposta un valore che indica se il popup può essere ignorato toccando all'esterno del popup. In Android: quando false il pulsante Indietro hardware è disabilitato.
Color	Color	Ottiene o imposta l'oggetto Color del popup. Questo colore imposta il colore di sfondo nativo di Popup, indipendentemente da qualsiasi colore di sfondo configurato nell'effettivo Content.
Content	View	Ottiene o imposta il contenuto di cui eseguire il View rendering in Popup.
HorizontalOptions	LayoutAlignment	Ottiene o imposta l'oggetto LayoutAlignment per posizionare orizzontalmente Popup sullo schermo.
Result	Task<object?>	Ottiene il risultato finale dell'oggetto ignorato Popup.
Size	Size	Ottiene o imposta l'oggetto Size della visualizzazione popup. Il popup tenterà sempre di vincolare le dimensioni effettive dell'oggetto Popup alle dimensioni della visualizzazione, a meno che non venga specificato un oggetto Size . Popup Se utilizza le HorizontalOptions proprietà o VerticalOptions che non sono le impostazioni predefinite, questa Size proprietà è obbligatoria.
VerticalOptions	LayoutAlignment	Ottiene o imposta l'oggetto LayoutAlignment per il posizionamento Popup verticale sullo schermo.

Eventi

Evento	Descrizione
Closed	Si verifica quando l'oggetto Popup viene chiuso.
Opened	Si verifica all'apertura dell'oggetto Popup .

Esempi

È possibile trovare un esempio di questa funzionalità in azione nell'applicazione di esempio .NET MAUI Community Toolkit.

API

È possibile trovare il codice sorgente per Popup over nel repository GitHub di .NET MAUI Community Toolkit.