Dialogsteuerelemente

Dialogsteuerelemente sind modale Benutzeroberflächenüberlagerungen, die kontextbezogene App-Informationen enthalten. Sie blockieren Interaktionen mit dem App-Fenster, bis sie ausdrücklich geschlossen werden. Sie verlangen häufig eine Aktion vom Benutzer.

Ist dies das richtige Steuerelement?

Verwenden Sie Dialogfelder, um Benutzern wichtige Informationen mitzuteilen oder deren Bestätigung bzw. zusätzliche Informationen anzufordern, bevor eine Aktion abgeschlossen werden kann.

Empfehlungen dazu, wann ein Dialogfeld und wann ein Flyout (ein ähnliches Steuerelement) verwendet werden sollte, finden Sie unter Dialogfelder und Flyouts.

Allgemeine Richtlinien

• Identifizieren Sie das Problem oder das Ziel des Benutzers in der ersten Zeile des Dialogfeldtexts eindeutig.
• Der Dialogtitel ist die Hauptanweisung und optional.
  • Verwenden Sie einen kurzen Titel, um zu erläutern, was im Dialogfeld zu tun ist.
  • Wenn Sie das Dialogfeld verwenden, um eine einfache Nachricht, einen Fehler oder eine Frage zu übermitteln, können Sie optional den Titel weglassen. Verlassen Sie sich auf den Inhaltstext, um diese Kerninformationen bereitzustellen.
  • Stellen Sie sicher, dass sich der Titel direkt auf die Auswahlmöglichkeiten der Schaltfläche bezieht.
• Der Dialoginhalt enthält den beschreibenden Text und ist erforderlich.
  • Stellen Sie die Nachricht, den Fehler oder die Blockierungsfrage so einfach wie möglich dar.
  • Wenn ein Dialogfeldtitel verwendet wird, verwenden Sie den Inhaltsbereich, um weitere Details bereitzustellen oder Terminologie zu definieren. Wiederholen Sie den Titel nicht mit leicht abweichenden Formulierungen.
• Mindestens eine Dialogfeldschaltfläche muss angezeigt werden.
  • Stellen Sie sicher, dass Ihr Dialogfeld mindestens eine Schaltfläche enthält, die eine sichere, nicht-destruktive Aktion wie „Alles klar!“, „Schließen“ oder „Abbrechen“ auslöst. Verwenden Sie die CloseButton-API, um diese Schaltfläche hinzuzufügen.
  • Verwenden Sie für den Schaltflächentext konkrete Antworten auf die Hauptanweisung oder den Inhalt. Beispiel: "Möchten Sie AppName auf Ihren Standort zugreifen lassen?", gefolgt von den Schaltflächen "Zulassen" und "Blockieren". Spezifische Antworten können schneller verstanden werden, was zu einer effizienten Entscheidungsfindung führt.
  • Stellen Sie sicher, dass der Text der Aktionsschaltflächen kurz ist. Kurze Anweisungen ermöglichen dem Benutzer, eine Entscheidung schnell und zuverlässig zu treffen.
  • Zusätzlich zur sicheren, nicht-destruktiven Aktion können Sie dem Benutzer optional eine oder zwei Aktionsschaltflächen anzeigen, die im Zusammenhang mit der Hauptanweisung stehen. Diese „Ausführen“-Aktionsschaltflächen bestätigen den Hauptpunkt des Dialogfelds. Verwenden Sie die PrimaryButton- und SecondaryButton-APIs, um diese „ausführenden“ Aktionen hinzuzufügen.
  • Die „bestätigenden“ Aktionsschaltflächen sollten als die am weitesten links stehenden Schaltflächen angezeigt werden. Die sichere, nicht-destruktive Aktion sollte als die am weitesten rechts stehende Schaltfläche angezeigt werden.
  • Sie können optional eine der drei Schaltflächen als Standardschaltfläche des Dialogfelds festlegen. Verwenden Sie die DefaultButton-API, um eine der Schaltflächen abzugrenzen.
• Verwenden Sie keine Dialogfelder für Fehler, die auf eine bestimmte Stelle auf der Seite kontextbezogen sind, z. B. Überprüfungsfehler (z. B. in Kennwortfeldern), verwenden Sie die Canvas der App selbst, um Inlinefehler anzuzeigen.
• Verwenden Sie die ContentDialog-Klasse, um Ihre Dialogfeldumgebung zu erstellen. Verwenden Sie nicht die veraltete MessageDialog-API.

Dialogfeld erstellen

Die WinUI 3 Gallery-App enthält interaktive Beispiele für WinUI-Steuerelemente und -Features. Rufen Sie die App aus dem Microsoft Store ab, oder durchsuchen Sie den Quellcode auf GitHub.

Zum Erstellen eines Dialogfelds verwenden Sie die ContentDialog-Klasse. Sie können ein Dialogfeld im Code oder Markup erstellen. Obwohl es in der Regel einfacher ist, UI-Elemente in XAML zu definieren, kann es im Falle eines einfachen Dialogfelds einfacher sein, Code zu verwenden. In diesem Beispiel wird ein Dialogfeld erstellt, in dem der Benutzer benachrichtigt wird, dass keine WLAN-Verbindung vorhanden ist, und anschließend wird die ShowAsync-Methode verwendet, um sie anzuzeigen.

private async void DisplayNoWifiDialog()
{
    ContentDialog noWifiDialog = new ContentDialog
    {
        Title = "No wifi connection",
        Content = "Check your connection and try again.",
        CloseButtonText = "OK"
    };

    ContentDialogResult result = await noWifiDialog.ShowAsync();
}

Wenn Ihr Inhaltsdialogfeld komplexer ist, kann es einfacher sein, es mit XAML zu erstellen. Sie können sie entweder in der XAML-Datei für Ihre Seite erstellen, oder Sie können eine Unterklasse von ContentDialog mit einer eigenen XAML- und CodeBehind-Datei erstellen. Vollständige Beispiele für beide Finden Sie in der [ContentDialog]-Klassenreferenz.

Es gibt keine Elementvorlage in Visual Studio zum Erstellen einer neuen Inhaltsdialogdatei. Sie können jedoch die Vorlage "Leere Seite" verwenden und die resultierenden Dateien ändern, um ein Dialogfeld zu erstellen.

So erstellen Sie ein neues Inhaltsdialogfeld mit XAML und CodeBehind

1. Klicken Sie im Bereich Solution Explorer mit der rechten Maustaste auf den Projektnamen und wählen Sie Neues Element hinzufügen...
2. Wählen Sie im Dialogfeld " Neues Element hinzufügen " winUI in der Vorlagenliste auf der linken Seite des Fensters aus.
3. Wählen Sie die Vorlage "Leere Seite " aus.
4. Benennen Sie die Datei. (In diesem Beispiel heißt XamlContentDialogdie Datei ).
5. Drücken Sie Hinzufügen.

Ändern Sie in der neuen XAML-Datei die öffnenden und schließenden Page-Tags in ContentDialog.

<!--
<Page
    x:Class="ContentDialog_WinUI3.XamlContentDialog"
    ...>

</Page>
-->

<ContentDialog
    x:Class="ContentDialog_WinUI3.XamlContentDialog"
    ...>

</ContentDialog>

Lassen Sie Ihre Klasse in der .xaml.cs-Datei von ContentDialog anstatt von Page erben.

// public sealed partial class XamlContentDialog : Page

public sealed partial class XamlContentDialog : ContentDialog

Dialogfeld anzeigen

Rufen Sie zum Anzeigen eines Dialogfelds die ShowAsync-Methode auf.

XamlContentDialog xamlDialog = new XamlContentDialog()
{
    XamlRoot = this.XamlRoot
};
await xamlDialog.ShowAsync();

Festlegen von XamlRoot

Wenn Sie ein ContentDialog anzeigen, müssen Sie das XamlRoot des Dialogfelds manuell auf den Stamm des XAML-Hosts festlegen. Um dies zu tun, legen Sie die XamlRoot-Eigenschaft des ContentDialog auf dasselbe XamlRoot wie ein Element fest, das bereits im XAML-Baum enthalten ist.

Wenn der ContentDialog von einer Seite angezeigt wird, können Sie die XamlRoot-Eigenschaft von ContentDialog auf "XamlRoot" der Seite festlegen, wie im vorherigen Beispiel gezeigt.

Das Fenster verfügt nicht über eine XamlRoot-Eigenschaft. Wenn das Dialogfeld aus einem Fenster angezeigt wird, legen Sie die XamlRoot-Eigenschaft des Dialogfelds auf die des Stamminhaltselements des Fensters fest, wie hier gezeigt.

<Window
    ... >
    <Grid x:Name="rootPanel">
    
    </Grid>
</Window>

private async void DisplayNoWifiDialog()
{
    ContentDialog noWifiDialog = new ContentDialog
    {
        XamlRoot = rootPanel.XamlRoot,
        Title = "No wifi connection",
        Content = "Check your connection and try again.",
        CloseButtonText = "Ok"
    };

    ContentDialogResult result = await noWifiDialog.ShowAsync();
}

Auf Dialogschaltflächen antworten

Wenn der Benutzer auf eine Dialogfeldschaltfläche klickt, gibt die ShowAsync-Methode ein ContentDialogResult zurück, um Ihnen mitzuteilen, auf welche Schaltfläche der Benutzer klickt.

Das Dialogfeld in diesem Beispiel stellt eine Frage und verwendet das zurückgegebene ContentDialogResult , um die Antwort des Benutzers zu bestimmen.

private async void DisplayDeleteFileDialog()
{
    ContentDialog deleteFileDialog = new ContentDialog
    {
        Title = "Delete file permanently?",
        Content = "If you delete this file, you won't be able to recover it. Do you want to delete it?",
        PrimaryButtonText = "Delete",
        CloseButtonText = "Cancel"
    };

    ContentDialogResult result = await deleteFileDialog.ShowAsync();

    // Delete the file if the user clicked the primary button.
    /// Otherwise, do nothing.
    if (result == ContentDialogResult.Primary)
    {
        // Delete the file.
    }
    else
    {
        // The user clicked the CloseButton, pressed ESC, Gamepad B, or the system back button.
        // Do nothing.
    }
}

Bereitstellen einer sicheren Maßnahme

Weil Dialogfelder eine Benutzerinteraktion blockieren und Schaltflächen das primäre Mittel für die Benutzer zum Schließen eines Dialogfelds sind, sollten Sie sicherstellen, dass Ihr Dialogfeld mindestens eine „sichere“, nicht-destruktive Schaltfläche wie z.B. „Schließen“ oder „Alles klar!“ enthält. Alle Dialogfelder sollten mindestens eine sichere Aktionsschaltfläche zum Schließen enthalten. Dadurch wird sichergestellt, dass der Benutzer das Dialogfeld zuverlässig schließen kann, ohne eine Aktion auszuführen.

private async void DisplayNoWifiDialog()
{
    ContentDialog noWifiDialog = new ContentDialog
    {
        Title = "No wifi connection",
        Content = "Check your connection and try again.",
        CloseButtonText = "OK"
    };

    ContentDialogResult result = await noWifiDialog.ShowAsync();
}

Wenn Dialogfelder dazu verwendet werden, eine blockierende Frage anzuzeigen, sollte Ihr Dialogfeld dem Benutzer Aktionsschaltflächen im Zusammenhang mit dieser Frage anzeigen. Die „sichere“, nicht-destruktive Schaltfläche kann durch eine oder zwei „bestätigende“ Aktionsschaltflächen ergänzt werden. Wenn dem Benutzer mehrere Optionen angezeigt werden, stellen Sie sicher, dass die Schaltflächen für die „bestätigende“ und die sichere/„ablehnende“ Aktion den Bezug zur Frage eindeutig darstellen.

private async void DisplayLocationPromptDialog()
{
    ContentDialog locationPromptDialog = new ContentDialog
    {
        Title = "Allow AppName to access your location?",
        Content = "AppName uses this information to help you find places, connect with friends, and more.",
        CloseButtonText = "Block",
        PrimaryButtonText = "Allow"
    };

    ContentDialogResult result = await locationPromptDialog.ShowAsync();
}

Dialogfelder mit drei Schaltflächen werden verwendet, wenn Sie dem Benutzer zwei „bestätigende“ Aktionen und eine „ablehnende“ Aktion bieten möchten. Dialogfelder mit drei Schaltflächen sollten sparsam verwendet werden und eine klare Unterscheidung zwischen der Sekundäraktion und der sicheren/ablehnenden Aktion enthalten.

private async void DisplaySubscribeDialog()
{
    ContentDialog subscribeDialog = new ContentDialog
    {
        Title = "Subscribe to App Service?",
        Content = "Listen, watch, and play in high definition for only $9.99/month. Free to try, cancel anytime.",
        CloseButtonText = "Not Now",
        PrimaryButtonText = "Subscribe",
        SecondaryButtonText = "Try it"
    };

    ContentDialogResult result = await subscribeDialog.ShowAsync();
}

Die drei Schaltflächen des Dialogfelds

„ContentDialog“ umfasst drei unterschiedliche Arten von Schaltflächen, die Sie zur Erstellung einer Dialogfeldumgebung verwenden können.

• CloseButton – erforderlich – Stellt die sichere, nicht-destruktive Aktion dar, die es dem Benutzer ermöglicht, das Dialogfeld zu schließen. Wird als die am weitesten rechts stehende Schaltfläche angezeigt.
• PrimaryButton – optional – Stellt die erste „bestätigende“ Aktion dar. Wird als die am weitesten links stehende Schaltfläche angezeigt.
• SecondaryButton – optional – Stellt die zweite „Ausführen“-Aktion dar. Wird als die mittlere Schaltfläche angezeigt.

Mithilfe der integrierten Schaltflächen können die Schaltflächen passend ausgerichtet werden, sodass sie korrekt auf Tastatureingaben reagieren. Dabei bleibt der Befehlsbereich sichtbar, selbst wenn die Bildschirmtastatur aufgerufen wird, und das Dialogfeld wird visuell an andere Dialogfelder angepasst.

Schließen-Schaltfläche

Jedes Dialogfeld sollte eine sichere, nicht-destruktive Aktionsschaltfläche enthalten, die dem Benutzer das zuverlässige Beenden ermöglicht.

Verwenden Sie die ContentDialog.CloseButton-API, um diese Schaltfläche zu erstellen. Dadurch schaffen Sie die jeweils richtige Benutzerumgebung für alle Eingabemöglichkeiten wie z.B. Maus, Tastatur, Toucheingabe und Gamepad. Dieses Erlebnis wird eintreten, wenn:

• Der Benutzer klickt oder tippt auf die Schaltfläche "Schließen".
• Der Benutzer drückt die Zurück-Taste des Systems.
• Der Benutzer drückt die ESC-Taste auf der Tastatur.
• Der Benutzer drückt Gamepad B.

Wenn der Benutzer auf eine Dialogfeldschaltfläche klickt, gibt die ShowAsync-Methode ein ContentDialogResult zurück, um Ihnen mitzuteilen, auf welche Schaltfläche der Benutzer klickt. Beim Klicken auf CloseButton wird „ContentDialogResult.None“ zurückgegeben.

Primärknopf und Sekundärknopf

Zusätzlich zu CloseButton können Sie dem Benutzer optional ein oder zwei Aktionsschaltflächen anzeigen, die im Zusammenhang mit der Hauptanweisung stehen. Nutzen Sie PrimaryButton für die erste „bestätigende“ Aktion und SecondaryButton für die zweite „bestätigende“ Aktion. Bei Dialogfeldern mit drei Schaltflächen stellt der PrimaryButton in der Regel die bejahende "ausführen" Aktion dar, während der SecondaryButton in der Regel eine neutrale oder sekundäre "ausführen" Aktion darstellt. Beispielsweise kann eine App den Benutzer dazu auffordern, einen Dienst zu abonnieren. In diesem Fall ist die PrimaryButton die "affirmative 'do it'"-Aktion und enthält den Text „Abonnieren“, während die SecondaryButton als neutrale "do it"-Aktion den Text „Ausprobieren“ enthält. Die Schließen-Schaltfläche ermöglicht es dem Benutzer, abzubrechen, ohne eine der beiden Aktionen durchzuführen.

Wenn der Benutzer auf die PrimaryButton klickt, gibt die ShowAsync-Methode „ContentDialogResult.Primary“ zurück. Klickt der Benutzer auf SecondaryButton, wird von der ShowAsync-Methode „ContentDialogResult.Secondary“ zurückgegeben.

Standard-Schaltfläche

Sie können optional eine der drei Schaltflächen als Standardschaltfläche festlegen. Das Festlegen einer Standardschaltfläche hat zur Folge, dass:

• Die Schaltfläche erhält die optische Gestaltung der Akzent-Schaltfläche.
• Die Schaltfläche antwortet automatisch auf die EINGABETASTE.
  • Wenn der Benutzer auf der Tastatur die EINGABETASTE drückt, wird der mit der Standardschaltfläche verknüpfte Click-Handler ausgelöst und „ContentDialogResult“ gibt den mit der Standardschaltfläche verknüpften Wert zurück.
  • Hat der Benutzer den Tastaturfokus auf ein Steuerelement gelegt, das die EINGABETASTE verarbeitet, reagiert die Standardschaltfläche nicht auf Tastendruck.
• Die Schaltfläche erhält den Fokus automatisch, wenn das Dialogfeld geöffnet wird – es sei denn, der Inhalt des Dialogfelds enthält eine fokussierbare Benutzeroberfläche.

Verwenden Sie die „ContentDialog.DefaultButton“-Eigenschaft, um die Standardschaltfläche anzugeben. Standardmäßig wird keine Standardschaltfläche festgelegt.

private async void DisplaySubscribeDialog()
{
    ContentDialog subscribeDialog = new ContentDialog
    {
        Title = "Subscribe to App Service?",
        Content = "Listen, watch, and play in high definition for only $9.99/month. Free to try, cancel anytime.",
        CloseButtonText = "Not Now",
        PrimaryButtonText = "Subscribe",
        SecondaryButtonText = "Try it",
        DefaultButton = ContentDialogButton.Primary
    };

    ContentDialogResult result = await subscribeDialog.ShowAsync();
}

Bestätigungsdialog (OK/Abbrechen)

Ein Bestätigungsdialogfeld gibt Benutzern die Möglichkeit, zu bestätigen, dass sie eine Aktion ausführen möchten. Sie können die Aktion bestätigen oder die Aktion abbrechen. Ein typisches Bestätigungsdialogfeld enthält zwei Schaltflächen: eine Bestätigungsschaltfläche ("OK") und eine Schaltfläche "Abbrechen".

• Im Allgemeinen sollte sich die Bestätigungsschaltfläche links (die primäre Schaltfläche) und die Schaltfläche "Abbrechen" (sekundäre Schaltfläche) auf der rechten Seite befindet.

  
• Wie im Abschnitt "Allgemeine Empfehlungen" erwähnt, verwenden Sie Schaltflächen mit Text, die bestimmte Antworten auf die Hauptanweisung oder den Hauptinhalt identifiziert.

„ContentDialog“ in „AppWindow“ oder „XAML-Inseln“

HINWEIS: Dieser Abschnitt gilt nur für Apps, die auf Windows 10, Version 1903 oder höher abzielen. „AppWindow“ und „XAML-Inseln“ sind in früheren Versionen nicht verfügbar. Weitere Informationen zu Versionen finden Sie unter Versionsadaptive Apps.

Inhaltsdialogfelder werden standardmäßig modal relativ zum Stamm ApplicationView angezeigt. Wenn Sie „ContentDialog“ in einem AppWindow oder einer XAML-Insel verwenden, müssen Sie den Wert für XamlRoot im Dialogfeld manuell auf den Stamm des XAML-Hosts festlegen.

Um dies zu tun, legen Sie die XamlRoot-Eigenschaft von ContentDialog auf dasselbe XamlRoot wie ein Element fest, das bereits im AppWindow oder in einer XAML Island vorhanden ist, wie hier gezeigt.

private async void DisplayNoWifiDialog()
{
    ContentDialog noWifiDialog = new ContentDialog
    {
        Title = "No wifi connection",
        Content = "Check your connection and try again.",
        CloseButtonText = "OK"
    };

    // Use this code to associate the dialog to the appropriate AppWindow by setting
    // the dialog's XamlRoot to the same XamlRoot as an element that is already present in the AppWindow.
    if (ApiInformation.IsApiContractPresent("Windows.Foundation.UniversalApiContract", 8))
    {
        noWifiDialog.XamlRoot = elementAlreadyInMyAppWindow.XamlRoot;
    }

    ContentDialogResult result = await noWifiDialog.ShowAsync();
}

Verwandte Artikel

• Quickinfos
• Menüs und Kontextmenü
• Flyout-Klasse
• ContentDialog-Klasse