Okno podręczne

Wyskakujące okienka to bardzo typowy sposób prezentowania informacji użytkownikowi, który odnosi się do bieżącego zadania. Systemy operacyjne zapewniają sposób wyświetlania komunikatu i wymagają odpowiedzi od użytkownika. Te alerty są zwykle restrykcyjne pod względem zawartości, która może zapewnić deweloper, a także układ i wygląd.

Uwaga

Jeśli chcesz przedstawić coś użytkownikowi, który jest bardziej subtelny, sprawdź nasze opcje Wyskakujące i Przekąski .

Widok Popup umożliwia deweloperom tworzenie własnego niestandardowego interfejsu użytkownika i prezentowanie go użytkownikom.

Tworzenie okna podręcznego

Element Popup można utworzyć w języku XAML lub C#:

XAML

Dołączanie przestrzeni nazw XAML

Aby można było używać zestawu narzędzi w języku XAML, należy dodać następujące xmlns elementy do strony lub widoku:

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

W związku z tym następujące elementy:

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

Zostanie zmodyfikowana tak, aby zawierała następujące xmlns elementy:

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

Definiowanie okna podręcznego

Należy pamiętać, że jeśli element Popup został utworzony w języku XAML, musi również mieć kod C# za plikiem. Aby dowiedzieć się, dlaczego jest to wymagane, zapoznaj się z tą stroną dokumentacji programu .NET MAUI.

Najprostszym sposobem utworzenia obiektu Popup jest dodanie nowego .NET MAUI ContentView (XAML) elementu do projektu, a następnie zmianę każdego z plików na następujące:

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

Ważne

Jeśli kod pliku nie zostanie utworzony wraz z wywołaniem metody , InitializeComponent podczas próby wyświetlenia elementu Popupzostanie zgłoszony wyjątek .

C#

using CommunityToolkit.Maui.Views;

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

Prezentowanie wyskakującego okienka

Po utworzeniu Popup obiektu można go przedstawić przy użyciu naszych Popup metod rozszerzeń lub implementacji IPopupService z tego zestawu narzędzi.

Ważne

Obiekt Popup można wyświetlić tylko z Page implementacji lub dziedziczonej z Pageklasy .

using CommunityToolkit.Maui.Views;

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

        this.ShowPopup(popup);
    }
}

Zamykanie okna podręcznego

Istnieją 2 różne sposoby, które Popup można zamknąć; programowo lub naciskając poza wyskakującym okienkiem.

Programowe zamykanie okna podręcznego

Aby zamknąć Popup dewelopera, musi wywołać Close lub CloseAsync na Popup sam. Jest to zwykle wykonywane przez odpowiadanie na naciśnięcie przycisku od użytkownika.

Możemy ulepszyć poprzedni przykład XAML, dodając przycisk 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>

W wynikowej procedurze obsługi zdarzeń wywołujemy Closemetodę , spowoduje to programowe zamknięcie obiektu Popup.

Uwaga

Close() jest metodą fire-and-forget. Zostanie on ukończony i powróci do wątku wywołującego, zanim system operacyjny odrzuci Popup element z ekranu. Jeśli musisz wstrzymać wykonywanie kodu, dopóki system operacyjny nie odrzuci Popup go z ekranu, użyj polecenia zamiast CloseAsync().

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

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

W wynikowej procedurze obsługi zdarzeń wywołujemy CloseAsyncmetodę , spowoduje to programowe zamknięcie Popup obiektu wywołującego do metody, await dopóki system operacyjny nie odrzuci Popup elementu z ekranu.

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

Naciśnięcie na zewnątrz okna podręcznego

Domyślnie użytkownik może nacisnąć poza element , Popup aby go odrzucić. Można to kontrolować za pomocą CanBeDismissedByTappingOutsideOfPopup właściwości . Ustawienie tej właściwości w taki sposób, aby false uniemożliwić użytkownikowi odrzucenie obiektu Popup przez naciśnięcie poza nią.

Zwracanie wyniku

Deweloper będzie często szukał odpowiedzi od użytkownika. Popup Widok umożliwia deweloperom zwrócenie wyniku, którego można oczekiwać i na które działa.

Możemy ulepszyć nasz oryginalny przykład XAML, aby pokazać, jak można to osiągnąć:

XAML

Dodając 2 nowe przyciski do kodu 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>

Następnie dodaj następujące programy obsługi zdarzeń w języku 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);
}

Metoda Close umożliwia object dostarczenie wartości. Będzie to wynikowa wartość zwracana. Aby oczekiwać na wynik, ShowPopupAsync należy użyć metody w następujący sposób:

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

Uwaga

Aby obsłużyć naciśnięcie poza obiektem Popup , gdy również oczekuje na wynik, możesz zmienić wartość zwracaną za pośrednictwem ResultWhenUserTapsOutsideOfPopup właściwości .

Style

Klasa Popup umożliwia korzystanie ze stylów MAUI platformy .NET, aby ułatwić udostępnianie typowych ustawień wizualnych w wielu oknach podręcznych.

W poniższym przykładzie pokazano, jak zdefiniować styl, który ma zastosowanie do przykładu SimplePopup z poprzedniej sekcji.

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

Uwaga

Tworząc obiekt Style docelowy Popup i chcesz zastosować je do niestandardowych wyskakujących okienek, takich jak SimplePopup przykład, upewnij się, że właściwość jest ApplyToDerivedTypes ustawiona Style na definicji.

Właściwości

Właściwości	Type	Opis
Anchor	View	Pobiera lub ustawia kotwicę View . Kotwica to miejsce, w którym okienko podręczne będzie renderowane najbliżej. Po skonfigurowaniu kotwicy wyskakujące okienko pojawi się wyśrodkowane nad kontrolką lub jak najbliżej tej kontrolki.
CanBeDismissedByTappingOutsideOfPopup	bool	Pobiera lub ustawia wartość wskazującą, czy wyskakujące okienko może zostać odrzucone przez naciśnięcie spoza okna podręcznego. W systemie Android — jeśli przycisk wstecz sprzętu jest wyłączony.
Color	Color	Pobiera lub ustawia Color wyskakujące okienka. Ten kolor ustawia natywny Popupkolor tła elementu , który jest niezależny od dowolnego koloru tła skonfigurowanego w rzeczywistej wartości Content.
Content	View	Pobiera lub ustawia zawartość do renderowania View w obiekcie Popup.
HorizontalOptions	LayoutAlignment	Pobiera lub ustawia LayoutAlignment element do ustawiania Popup pozycji poziomej na ekranie.
Result	Task<object?>	Pobiera końcowy wynik odrzuconego Popupobiektu .
Size	Size	Pobiera lub ustawia Size wyświetlanie wyskakujących okienek. Okno podręczne zawsze będzie próbowało ograniczyć rzeczywisty rozmiar Popup do rozmiaru widoku, chyba że Size zostanie określony. Popup Jeśli używa HorizontalOptions właściwości lubVerticalOptions, które nie są wartościami domyślnymi, ta Size właściwość jest wymagana.
VerticalOptions	LayoutAlignment	Pobiera lub ustawia element LayoutAlignment do pozycjonowania Popup w pionie na ekranie.

Zdarzenia

Wydarzenie	Opis
Closed	Występuje po Popup zamknięciu.
Opened	Występuje po otwarciu Popup .

Przykłady

Przykład tej funkcji można znaleźć w aplikacji przykładowej zestawu narzędzi .NET MAUI Community Toolkit.

interfejs API

Kod źródłowy można Popup znaleźć w repozytorium GitHub zestawu narzędzi .NET MAUI Community Toolkit.