Popup-meny

Popup-fönster är ett mycket vanligt sätt att presentera information för en användare som relaterar till deras aktuella uppgift. Operativsystem ger ett sätt att visa ett meddelande och kräva ett svar från användaren, dessa aviseringar är vanligtvis restriktiva när det gäller innehållet som en utvecklare kan tillhandahålla och även layout och utseende.

Notera

Om du vill presentera något för användaren som är mer subtil kan du kolla in våra Toast och Snackbar alternativ.

Med Popup-vyn kan utvecklare skapa ett eget anpassat användargränssnitt och presentera det för sina användare.

Skapa ett popup-fönster

En Popup kan skapas i XAML eller C#:

XAML

Inklusive XAML-namnområdet

För att kunna använda verktygslådan i XAML måste följande xmlns läggas till på sidan eller vyn:

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

Därför följande:

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

Skulle ändras för att inkludera xmlns på följande sätt:

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

Definiera ditt popup-fönster

Observera att om en Popup skapas i XAML måste den också ha en C#-kod bakom filen. Information om varför detta krävs finns på den här .NET MAUI-dokumentationssidan.

Det enklaste sättet att skapa en Popup är att lägga till en ny .NET MAUI ContentView (XAML) i projektet och sedan ändra var och en av filerna till följande:

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

Viktig

Om koden bakom filen inte skapas tillsammans med anropet till InitializeComponent genereras ett undantag när du försöker visa Popup.

C#

using CommunityToolkit.Maui.Views;

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

Att visa ett popup-fönster

När Popup har skapats kan den sedan presenteras med hjälp av våra Popup tilläggsmetoder eller genom IPopupService implementering från den här verktygslådan.

Viktig

En Popup kan bara visas från en Page eller en implementering som ärver från Page.

using CommunityToolkit.Maui.Views;

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

        this.ShowPopup(popup);
    }
}

Stänga ett popup-fönster

Det finns två olika sätt att stänga en Popup. programmatiskt eller genom att trycka utanför popup-fönstret.

Programmatiskt stänga ett popup-fönster

För att stänga en Popup måste en utvecklare anropa Close eller CloseAsync på själva Popup. Detta utförs vanligtvis genom att svara på en knapptryckning från en användare.

Vi kan förbättra det tidigare XAML-exemplet genom att lägga till en 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>

I den resulterande händelsehanteraren som vi anropar med Closekommer detta att stänga Popupprogrammatiskt.

Not

Close() är en eld-och-glöm-metod. Den kommer att slutföra och återgå till den anropande tråden innan operativsystemet har avlägsnat Popup från skärmen. Om du behöver pausa körningen av koden tills operativsystemet har stängt Popup från skärmen använder du i stället CloseAsync().

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

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

I den resulterande händelsehanteraren som vi anropar CloseAsyncstänger detta programmatiskt Popup så att anroparen kan await metoden tills operativsystemet har stängt Popup från skärmen.

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

Tryck utanför popup-fönstret

Som standardinställning kan en användare trycka utanför Popup för att avfärda den. Detta kan styras med hjälp av egenskapen CanBeDismissedByTappingOutsideOfPopup. Om du anger den här egenskapen till false förhindrar du att en användare kan stänga Popup genom att trycka utanför den.

Returnera ett resultat

En utvecklare kommer ganska ofta att söka ett svar från sina användare, Popup-vyn gör det möjligt för utvecklare att returnera ett resultat som kan inväntas och ageras på.

Vi kan förbättra vårt ursprungliga XAML-exempel för att visa hur detta kan åstadkommas:

XAML

Genom att lägga till två nya knappar i 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>

Lägg sedan till följande händelsehanterare i 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);
}

Med metoden Close kan ett object värde anges, vilket blir det resulterande returvärdet. För att invänta resultatet måste metoden ShowPopupAsync användas på följande sätt:

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

Not

För att hantera tryckningen utanför en Popup när du också väntar på resultatet kan du ändra värdet som returneras via egenskapen ResultWhenUserTapsOutsideOfPopup.

Styling

Med klassen Popup kan du använda .NET MAUI Styles för att göra det enklare att dela vanliga visuella inställningar i flera popup-fönster.

I följande exempel visas hur du definierar ett format som gäller för SimplePopup exempel från föregående avsnitt.

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

Anteckning

När du skapar en Style som riktar sig mot Popup och du vill att den ska tillämpas på anpassade popup-fönster som i SimplePopup exempel måste du ange egenskapen ApplyToDerivedTypes för definitionen Style.

Egenskaper

Egenskap	Typ	Beskrivning
Anchor	View	Hämtar eller anger View fästpunkt. Fästpunkten är där popup-fönstret visas närmast. När en fästpunkt har konfigurerats visas popup-fönstret centrerat över den kontrollen eller så nära som möjligt.
CanBeDismissedByTappingOutsideOfPopup	bool	Hämtar eller anger ett värde som anger om popup-fönstret kan stängas genom att trycka utanför popup-fönstret. På Android – när 'false' är bakåtknappen för hårdvara inaktiverad.
Color	Color	Hämtar och ställer in Color för popup-fönstret. Den här färgen anger den inbyggda bakgrundsfärgen för Popup, som är oberoende av bakgrundsfärgen som konfigurerats i den faktiska Content.
Content	View	Hämtar eller ställer in View-innehållet som ska återges i Popup.
HorizontalOptions	LayoutAlignment	Hämtar eller ställer in LayoutAlignment för att placera Popup vågrätt på skärmen.
Result	Task<object?>	Hämtar slutresultatet av den avvisade Popup.
Size	Size	Hämtar eller anger Size för popupfönstret. Popup-fönstret försöker alltid begränsa den faktiska storleken på Popup till storleken på vyn såvida inte en Size har angetts. Om Popup använder egenskaperna HorizontalOptions eller VerticalOptions som inte är standardvärdena krävs den här Size egenskapen.
VerticalOptions	LayoutAlignment	Hämtar eller anger LayoutAlignment för att placera Popup lodrätt på skärmen.

Evenemang

Händelse	Beskrivning
Closed	Inträffar när Popup stängs.
Opened	Inträffar när Popup öppnas.

Exempel

Du hittar ett exempel på den här funktionen i praktiken i .NET MAUI Community Toolkit Sample Application.

API

Du hittar källkoden för Popup på github-lagringsplatsen .NET MAUI Community Toolkit.