Popup

Artikel
03/19/2024

Popups sind eine sehr gängige Methode zum Darstellen von Informationen für einen Benutzer, die sich auf seine aktuelle Aufgabe beziehen. Betriebssysteme bieten eine Möglichkeit zum Anzeigen einer Nachricht und Anfordern einer Antwort des Benutzers. Diese Warnungen sind in der Regel in Bezug auf den Inhalt, den ein Entwickler bereitstellen kann, sowie das Layout und die Darstellung restriktiv.

Hinweis

Wenn Sie dem Benutzer Informationen etwas dezenter präsentieren möchten, schauen Sie sich unsere Toast- und Snackbar-Optionen an.

Mit der Ansicht Popup können Entwickler ihre eigene benutzerdefinierte Benutzeroberfläche erstellen und ihren Benutzern präsentieren.

Ein Popup kann in XAML oder C# erstellt werden:

XAML

Einbinden des XAML-Namespace

Um das Toolkit in XAML verwenden zu können, muss der folgende xmlns-Abschnitt zu Ihrer Seite oder Ansicht hinzugefügt werden:

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

Der folgende Abschnitt:

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

Würde dann geändert werden, um xmlns einzubinden:

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

Beachten Sie, dass bei der Erstellung eines Popup in XAML auch eine C#-CodeBehind-Datei vorhanden sein muss. Informationen dazu, warum dies erforderlich ist, finden Sie auf dieser .NET MAUI-Dokumentationsseite.

Die einfachste Möglichkeit zum Erstellen eines Popup besteht darin, Ihrem Projekt ein neues .NET MAUI ContentView (XAML)-Element hinzuzufügen und dann die einzelnen Dateien wie folgt zu ändern:

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

Wichtig

Wenn die CodeBehind-Datei nicht zusammen mit dem Aufruf von InitializeComponent erstellt wird, wird beim Versuch, das Popupanzuzeigen, eine Ausnahme ausgelöst.

C#

using CommunityToolkit.Maui.Views;

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

Sobald das Popup erstellt wurde, kann es dann mithilfe einer unserer Popup-Erweiterungsmethoden oder über die IPopupService-Implementierung aus diesem Toolkit präsentiert werden.

IPopupService

Das .NET MAUI Community Toolkit bietet einen Mechanismus zum Instanziieren und Präsentieren von Popups in einer .NET MAUI-Anwendung. Der Popupdienst wird bei Verwendung der UseMauiCommunityToolkit-Initialisierungsmethode automatisch beim MauiAppBuilder registriert. Auf diese Weise können Sie eine IPopupService-Implementierung in einem beliebigen Teil Ihrer Anwendung auflösen.

IPopupService ermöglicht das Registrieren einer Popupansicht und des zugehörigen Ansichtsmodells. Die Möglichkeit zum Anzeigen eines Popup kann jetzt nur durch die Bereitstellung des Ansichtsmodells gesteuert werden, sodass eine klare Trennung zwischen Ansicht und Ansichtsmodell gewährleistet werden kann.

Registrieren von Popups

Um zuerst den IPopupService zum Anzeigen eines Popups in Ihrer Anwendung zu verwenden, müssen Sie das Popup- und Ansichtsmodell beim MauiAppBuilder registrieren. Dies kann mithilfe der Informationen in Registrieren der Popupansicht und des Ansichtsmodells erfolgen.

Anzeigen von Popups

Das folgende Beispiel zeigt, wie Sie mithilfe des IPopupService ein Popup in einer .NET MAUI-Anwendung erstellen und anzeigen können:

public class MyViewModel : INotifyPropertyChanged
{
    private readonly IPopupService popupService;

    public MyViewModel(IPopupService popupService)
    {
        this.popupService = popupService;
    }

    public void DisplayPopup()
    {
        this.popupService.ShowPopup<UpdatingPopupViewModel>();
    }
}

Ein konkretes Beispiel finden Sie in unserer Beispielanwendung und im Beispiel in MultiplePopupViewModel.

Der IPopupService bietet außerdem Methoden zum Behandeln eines Ergebnisses, das von einem Popup zurückgegeben wird, wie in Zurückgeben eines Ergebnisses beschrieben.

Beim Präsentieren eines Popups müssen wir manchmal Daten an das zugrunde liegende Ansichtsmodell übergeben, damit dynamische Inhalte dem Benutzer präsentiert werden können. Der IPopupService ermöglicht dies über die Überladungen der ShowPopup- und der ShowPopupAsync-Methode, die einen Action<TViewModel> onPresenting-Parameter annehmen. Dieser Parameter wurde entwickelt, um frameworkagnostisch zu sein und es Ihnen als Entwickler zu ermöglichen, das Laden/Übergeben von Daten in einer Art und Weise durchzuführen, die am besten zu Ihrer Architektur passt.

Um das vorherige Beispiel für die Anzeige eines UpdatingPopupViewModel und des zugehörigen Popups zu erweitern, können wir den onPresenting-Parameter verwenden. Hiermit wird die Anzahl der Aktualisierungen übergeben, die wir ausführen möchten:

public class MyViewModel : INotifyPropertyChanged
{
    private readonly IPopupService popupService;

    public MyViewModel(IPopupService popupService)
    {
        this.popupService = popupService;
    }

    public void DisplayPopup()
    {
        this.popupService.ShowPopup<UpdatingPopupViewModel>(onPresenting: viewModel => viewModel.PerformUpdates(10));
    }
}

Erweiterungsmethoden

Wichtig

Ein Popup kann nur von einer Page oder einer Implementierung angezeigt werden, die von Page erbt.

using CommunityToolkit.Maui.Views;

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

        this.ShowPopup(popup);
    }
}

Es gibt 2 verschiedene Möglichkeiten, wie ein Popup geschlossen werden kann: programmgesteuert oder durch Tippen außerhalb des Popups.

Um ein Popup zu schließen, muss ein Entwickler Close oder CloseAsync für das Popup selbst aufrufen. Dies wird in der Regel ausgeführt, indem auf das Klicken auf eine Schaltfläche durch den Benutzer reagiert wird.

Wir können das vorherige XAML-Beispiel erweitern, indem wir einen OK-Button hinzufügen:

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

Im resultierenden Ereignishandler wird Close aufgerufen. Dadurch wird das Popup programmgesteuert geschlossen.

Hinweis

Close() ist eine Fire-and-Forget-Methode. Sie wird abgeschlossen und an den aufrufenden Thread zurückgegeben, bevor das Betriebssystem dasPopup auf dem Bildschirm geschlossen hat. Wenn Sie die Ausführung des Codes anhalten müssen, bis das Betriebssystem das Popup auf dem Bildschirm geschlossen hat, verwenden Sie stattdessen CloseAsync().

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

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

Im resultierenden Ereignishandler rufen wir CloseAsync auf. Dadurch wird das Popup programmgesteuert geschlossen, sodass für den Aufrufer ein await der Methode möglich ist, bis das Betriebssystem das Popup auf dem Bildschirm geschlossen hat.

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

Standardmäßig kann ein Benutzer außerhalb des Popup tippen, um es zu schließen. Dies kann über die Verwendung der CanBeDismissedByTappingOutsideOfPopup-Eigenschaft gesteuert werden. Wenn Sie diese Eigenschaft auf false festlegen, wird verhindert, dass ein Benutzer das Popup schließen kann, indem er außerhalb des Objekts tippt.

Zurückgeben eines Ergebnisses

Entwickler benötigen häufig eine Antwort des Benutzers. Die Popup-Ansicht ermöglicht es Entwicklern, ein Ergebnis zurückzugeben, das erwartet und auf das reagiert werden kann.

Wir können unser ursprüngliches XAML-Beispiel erweitern, um zu zeigen, wie dies erreicht werden kann:

XAML

Durch Hinzufügen von 2 neuen Schaltflächen zum XAML-Code:

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

Fügen Sie dann die folgenden Ereignishandler in C# hinzu:

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

Die Close-Methode ermöglicht die Angabe eines object-Werts. Dies ist der resultierende Rückgabewert. Um auf das Ergebnis zu warten, muss die ShowPopupAsync-Methode wie folgt verwendet werden:

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

Hinweis

Um das Tippen außerhalb eines Popup zu behandeln, wenn auch auf das Ergebnis gewartet wird, können Sie den Wert ändern, der über die ResultWhenUserTapsOutsideOfPopup-Eigenschaft zurückgegeben wird.

Format

Die Popup-Klasse ermöglicht die Verwendung von .NET MAUI-Formatvorlagen, um die gemeinsame visuellen Einstellungen für mehrere Popups einfacher zu gestalten.

Das folgende Beispiel zeigt, wie Sie eine Formatvorlage definieren, die auf das SimplePopup-Beispiel aus dem vorherigen Abschnitt angewendet wird.

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

Hinweis

Stellen Sie beim Erstellen eines Style, der auf Popup ausgerichtet ist und der auf benutzerdefinierte Popups wie im SimplePopup-Beispiel angewendet werden soll, sicher, dass Sie die ApplyToDerivedTypes-Eigenschaft für dieStyle-Definition festlegen.

Eigenschaften

Eigenschaft	Typ	Beschreibung
`Anchor`	`View`	Ruft den `View`-Anker ab oder legt ihn fest. Der Anker ist der Ort, in dessen unmittelbarer Nähe das Popup gerendert wird. Wenn ein Anker konfiguriert ist, wird das Popup zentriert über diesem Steuerelement oder so nah wie möglich angezeigt.
`CanBeDismissedByTappingOutsideOfPopup`	`bool`	Dient zum Abrufen oder Festlegen eines Werts, der angibt, ob das Popup geschlossen werden kann, indem der Benutzer außerhalb des Popups tippt. Android: Bei „false“ wird die Hardware-Zurück-Taste deaktiviert.
`Color`	`Color`	Ruft den `Color`-Wert des Popups ab oder legt ihn fest. Diese Farbe legt die native Hintergrundfarbe des `Popup`fest, die unabhängig von jeder Hintergrundfarbe ist, die im tatsächlichen `Content` konfiguriert ist.
`Content`	`View`	Ruft den `View`-Inhalt ab, der im `Popup` gerendert werden soll.
`HorizontalOptions`	`LayoutAlignment`	Ruft `LayoutAlignment` ab, um das `Popup` horizontal auf dem Bildschirm zu positionieren, oder legt den Wert fest.
`Result`	`Task<object?>`	Ruft das Endergebnis des geschlossenen `Popup` ab.
`Size`	`Size`	Ruft `Size` für die Popupanzeige ab oder legt den Wert fest. Das Popup versucht immer, die tatsächliche Größe des `Popup` auf die Größe der Ansicht zu beschränken, es sei denn, ein `Size`-Wert wurde angegeben. Wenn das `Popup` die `HorizontalOptions`- oder `VerticalOptions`-Eigenschaft verwendet, die nicht die Standardwerte sind, ist diese `Size`-Eigenschaft erforderlich.
`VerticalOptions`	`LayoutAlignment`	Ruft `LayoutAlignment` ab, um das `Popup` vertikal auf dem Bildschirm zu positionieren, oder legt den Wert fest.

Ereignisse

Event	Beschreibung
`Closed`	Das Ereignis, das aufgerufen wird, wenn das `Popup` geschlossen wird.
`Opened`	Das Ereignis, das aufgerufen wird, wenn das `Popup` geöffnet wird.

Beispiele

Sie finden ein Beispiel für dieses Feature in Aktion in der Beispielanwendung für das .NET MAUI Community Toolkit.

API

Sie finden den Quellcode für Popup über das GitHub-Repository für das .NET MAUI Community Toolkit.

XAML

Einbinden des XAML-Namespace

C#

IPopupService

Registrieren von Popups

Anzeigen von Popups

Erweiterungsmethoden

Zurückgeben eines Ergebnisses

XAML

Format

Eigenschaften

Ereignisse

Beispiele

API

Feedback

Zusätzliche Ressourcen

Erstellen eines Popups

XAML

Einbinden des XAML-Namespace

Definieren des Popups

C#

Darstellen eines Popups

IPopupService

Registrieren von Popups

Anzeigen von Popups

Übergeben von Daten an ein Popupansichtsmodell

Erweiterungsmethoden

Schließen eines Popups

Programmgesteuertes Schließen eines Popups

Tippen außerhalb des Popups

Zurückgeben eines Ergebnisses

XAML

Format

Eigenschaften

Ereignisse

Beispiele

API

Feedback

Zusätzliche Ressourcen