Ovládací prvky dialogového okna

Ovládací prvky dialogového okna jsou modální překryvy uživatelského rozhraní, které poskytují informace o kontextové aplikaci. Blokují interakce s oknem aplikace, dokud nejsou explicitně zavřeny. Často od uživatele požadují nějaký druh akce.

Příklad dialogového okna

Je to správná kontrola?

Pomocí dialogových oken můžete uživatelům oznámit důležité informace nebo požádat o potvrzení nebo další informace před dokončením akce.

Doporučení, kdy použít dialogové okno vs. kdy použít kontextový (podobný ovládací prvek), najdete v tématu Dialogy a kontextové rámečky.

Obecné pokyny

Jasně identifikujte problém nebo cíl uživatele v prvním řádku textu dialogového okna.
Název dialogového okna je hlavní instrukce a je nepovinný.
- Užijte krátký název, abyste vysvětlili, co mají lidé provést v dialogovém okně.
- Pokud k doručení jednoduché zprávy, chyby nebo otázky používáte dialogové okno, můžete název volitelně vynechat. Při doručování základních informací se spoléhá na text obsahu.
- Ujistěte se, že název souvisí přímo s volbami tlačítek.
Obsah dialogového okna obsahuje popisný text a je povinný.
- Prezentujte zprávu, chybu nebo blokující otázku co nejrychleji.
- Pokud se použije název dialogového okna, použijte oblast obsahu k zadání dalších podrobností nebo definování terminologie. Neopakujte název s mírně odlišným zněním.
Musí se zobrazit alespoň jedno tlačítko dialogového okna.
- Ujistěte se, že dialogové okno obsahuje alespoň jedno tlačítko odpovídající bezpečné, nedestruktivní akci, například "Got it!", "Close" nebo "Cancel". K přidání tohoto tlačítka použijte rozhraní API CloseButton.
- Jako text tlačítka použijte konkrétní odpovědi na hlavní instrukce nebo obsah. Příkladem je otázka: "Chcete aplikaci AppName povolit přístup k vaší poloze?", následovaná tlačítky "Povolit" a "Blokovat". Konkrétní odpovědi je možné pochopit rychleji, což vede k efektivnímu rozhodování.
- Ujistěte se, že text tlačítek akcí je stručný. Krátké řetězce umožňují uživateli rychle a s jistotou zvolit.
- Kromě bezpečné nedestruktivní akce můžete uživatele volitelně prezentovat jedním nebo dvěma tlačítky akcí souvisejícími s hlavní instrukcí. Tato potvrzovací tlačítka akce zdůrazňují hlavní bod dialogu. Pomocí rozhraní API PrimaryButton a SecondaryButton přidejte tyto akce "do it".
- Tlačítka akcí "Do it" by se měla zobrazit jako tlačítka úplně vlevo. Bezpečná, nedestruktivní akce by se měla zobrazit jako tlačítko úplně vpravo.
- Volitelně můžete zvolit rozlišení jednoho ze tří tlačítek jako výchozího tlačítka dialogového okna. K rozlišení jednoho z tlačítek použijte rozhraní API DefaultButton.
Nepoužívejte dialogy pro chyby, které se vztahují k určitému místu na stránce, jako jsou například chyby ověření (v heslových polích). Použijte samotné prostředí aplikace k zobrazení vložených chyb.
K vytvoření dialogového okna použijte třídu ContentDialog . Nepoužívejte zastaralé rozhraní MessageDialog API.

Vytvoření dialogového okna

Důležité API: třída ContentDialog

Otevřete aplikaci Galerie WinUI 3 a podívejte se na ContentDialog v akci.

Aplikace Galerie WinUI 3 obsahuje interaktivní příklady ovládacích prvků a funkcí WinUI. Získejte aplikaci z Microsoft Store nebo vyhledejte zdrojový kód na GitHub.

Chcete-li vytvořit dialogové okno, použijte ContentDialog třídy. Dialogové okno můžete vytvořit v kódu nebo ve značkovacím jazyce. I když je obvykle jednodušší definovat prvky uživatelského rozhraní v XAML, v případě jednoduchého dialogového okna může být jednodušší jednoduše používat kód. Tento příklad vytvoří dialogové okno, které uživatele upozorní, že neexistuje žádné připojení Wi-Fi, a pak k jeho zobrazení použije metodu ShowAsync .

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

Pokud je dialogové okno obsahu složitější, může být jednodušší ho vytvořit pomocí XAML. Můžete ho buď vytvořit v souboru XAML pro svou stránku, nebo můžete vytvořit podtřídu ContentDialog s vlastním souborem .xaml a podkladovým kódem. Kompletní příklady obou najdete v referenci třídy [ContentDialog].

V Visual Studio neexistuje žádná šablona položky k vytvoření nového souboru dialogového okna obsahu, ale můžete použít šablonu Prázdná stránka a upravit výsledné soubory k vytvoření dialogového okna.

Vytvoření nového dialogového okna s obsahem pomocí XAML a kódu na pozadí

V podokně Solution Explorer klikněte pravým tlačítkem myši na název projektu a vyberte Přidat > Nová položka...
V dialogovém okně Přidat novou položku vyberte WinUI v seznamu šablon na levé straně okna.
Vyberte šablonu Prázdná stránka .
Pojmenujte soubor . (V tomto příkladu je soubor pojmenován XamlContentDialog).
Stiskněte Přidat.

V novém souboru .xaml změňte otevírání a zavírání značek stránky na dialogové okno Obsah.

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

</Page>
-->

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

</ContentDialog>

V souboru .xaml.cs nechte třídu dědit z ContentDialogu namísto Page.

// public sealed partial class XamlContentDialog : Page

public sealed partial class XamlContentDialog : ContentDialog

Zobrazit dialogové okno

Dialogové okno zobrazíte voláním metody ShowAsync .

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

Výstraha

Najednou může být otevřeno pouze jedno okno ContentDialogu. Při pokusu o otevření dvou dialogových oken s obsahem dojde k výjimce.

Nastavení XamlRoot

Když zobrazíte ContentDialog, musíte ručně nastavit XamlRoot dialogového okna na kořen hostitele XAML. K tomu nastavte vlastnost XamlRoot elementu ContentDialog na stejný XamlRoot jako prvek již ve stromu XAML.

Pokud se ContentDialog zobrazí ze stránky, můžete nastavit Vlastnost XamlRoot contentDialogu na XamlRoot stránky, jak je znázorněno v předchozím příkladu.

Okno nemá vlastnost XamlRoot, takže pokud je dialogové okno zobrazeno z Okna, nastavte vlastnost XamlRoot dialogového okna na hodnotu kořenového prvku obsahu Okna, jak je znázorněno zde.

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

Reakce na tlačítka dialogového okna

Když uživatel klikne na tlačítko dialogového okna, metoda ShowAsync vrátí ContentDialogResult , abyste věděli, na které tlačítko uživatel klikne.

Dialogové okno v tomto příkladu položí otázku a použije vrácený ContentDialogResult k určení odpovědi uživatele.

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

Zajištění bezpečné akce

Vzhledem k tomu, že dialogy blokují interakci uživatele a protože tlačítka jsou primárním mechanismem pro zavření dialogového okna, ujistěte se, že dialogové okno obsahuje aspoň jedno bezpečné a nedestruktivní tlačítko, například "Zavřít" nebo "Získat!". Všechna dialogová okna by měla obsahovat alespoň jedno tlačítko bezpečné akce, aby se dialogové okno zavřely. Tím se zajistí, že uživatel může bez obav zavřít dialogové okno bez provedení akce.

Dialogové okno s jedním tlačítkem

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

Když se dialogy používají k zobrazení blokující otázky, měl by dialogové okno prezentovat uživatele s tlačítky akcí souvisejícími s danou otázkou. Tlačítko "bezpečné" a nedestruktivní může být doprovázeno jedním nebo dvěma tlačítky akcí "do it". Při předkládání uživateli více možností se ujistěte, že tlačítka jasně vysvětlují akce "udělat to" a bezpečné/"neudělat to" související s položenou otázkou.

Dialogové okno se dvěma tlačítky

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

Dialogy se třemi tlačítky se používají, když chcete uživateli nabídnout dvě akce "provést" a jednu akci "neprovádět". Tři dialogy tlačítek by se měly používat střídmě s jasnými rozdíly mezi sekundární akcí a akcí bezpečné/zavření.

Dialogové okno se třemi tlačítky

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

Tři dialogová tlačítka

ContentDialog má tři různé typy tlačítek, které můžete použít k vytvoření dialogového okna.

CloseButton - Required - Představuje bezpečnou nedestruktivní akci, která uživateli umožňuje ukončit dialogové okno. Zobrazí se jako tlačítko úplně vpravo.
PrimaryButton – Volitelné – Představuje první akci "provést". Zobrazí se jako tlačítko úplně vlevo.
SecondaryButton – Nepovinné – Představuje druhou akci "udělej to". Zobrazí se jako prostřední tlačítko.

Pomocí předdefinovaných tlačítek správně umístíte tlačítka, zajistíte, aby správně reagovaly na události klávesnice, aby byla oblast příkazů viditelná i v případě, že je klávesnice na obrazovce zapnutá, a aby dialogové okno vypadalo konzistentně s ostatními dialogy.

TlačítkoZavřít

Každé dialogové okno by mělo obsahovat bezpečné, nedestruktivní tlačítko akce, které uživateli umožní bez obav ukončit dialogové okno.

K vytvoření tohoto tlačítka použijte rozhraní API ContentDialog.CloseButton. To vám umožní vytvořit správné uživatelské prostředí pro všechny vstupy, včetně myši, klávesnice, dotykového ovládání a gamepadu. K této situaci dojde, když:

Uživatel klikne nebo klepne na tlačítko Zavřít.
Uživatel stiskne systémové tlačítko zpět.
Uživatel na klávesnici stiskne tlačítko ESC.
Uživatel stiskne Gamepad B.

Když uživatel klikne na tlačítko dialogového okna, metoda ShowAsync vrátí ContentDialogResult , abyste věděli, na které tlačítko uživatel klikne. Stisknutím klávesy CloseButton vrátíte ContentDialogResult.None.

Primární tlačítko a Sekundární tlačítko

Kromě closeButtonu můžete uživatele volitelně prezentovat jedním nebo dvěma tlačítky akcí souvisejícími s hlavní instrukcí. Využít PrimaryButton pro první akci "provést" a SecondaryButton pro druhou akci "provést". V dialogových oknech se třemi tlačítky obecně představuje primární tlačítko pozitivní akci "provést", zatímco SecondaryButton obecně představuje neutrální nebo sekundární akci "provést". Aplikace může například vyzvat uživatele, aby se přihlásil k odběru služby. Primární tlačítko, jako pozitivní akce "udělej to", by obsahovalo text Přihlásit k odběru, zatímco Sekundární tlačítko, jako neutrální akce "zkus to", by obsahovalo text Vyzkoušet. CloseButton by uživateli umožnil zrušit bez provedení žádné akce.

Když uživatel klikne na PrimaryButton, ShowAsync metoda vrátí ContentDialogResult.Primary. Když uživatel klikne na SecondaryButton, ShowAsync metoda vrátí ContentDialogResult.Secondary.

Dialogové okno se třemi tlačítky

Výchozí tlačítko

Volitelně můžete zvolit rozlišení jednoho ze tří tlačítek jako výchozího tlačítka. Zadání výchozího tlačítka způsobí, že dojde k následujícímu:

Tlačítko obdrží vizuální styl zvýrazňujícího tlačítka
Tlačítko automaticky odpoví na klávesu ENTER.
- Když uživatel stiskne klávesu ENTER na klávesnici, aktivuje se obslužná rutina kliknutí přidružená k výchozímu tlačítku a ContentDialogResult vrátí hodnotu přidruženou k výchozímu tlačítku.
- Pokud uživatel umístil fokus klávesnice na ovládací prvek, který zpracovává ENTER, výchozí tlačítko nereaguje na stisknutí klávesy ENTER.
Tlačítko získá fokus automaticky při otevření dialogového okna, pokud obsah dialogu neobsahuje zaostřitelné prvky uživatelského rozhraní.

K označení výchozího tlačítka použijte vlastnost ContentDialog.DefaultButton. Ve výchozím nastavení není nastavené žádné výchozí tlačítko.

Dialogové okno se třemi tlačítky s výchozím tlačítkem

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

Potvrzovací dialogy (OK/Zrušit)

Potvrzovací dialog umožňuje uživatelům potvrdit, že chtějí provést akci. Můžou potvrdit akci nebo se rozhodnout zrušit. Typický potvrzovací dialog obsahuje dvě tlačítka: tlačítko potvrzení (OK) a tlačítko zrušit.

Obecně platí, že tlačítko potvrzení by mělo být vlevo (primární tlačítko) a tlačítko zrušit (sekundární tlačítko) by mělo být vpravo.
Jak je uvedeno v části s obecnými doporučeními, použijte tlačítka s textem, který identifikuje konkrétní odpovědi na hlavní instrukce nebo obsah.

ContentDialog v AppWindow nebo Xaml Islands

POZNÁMKA: Tato část platí jenom pro aplikace, které cílí na Windows 10 verze 1903 nebo novější. V dřívějších verzích nejsou k dispozici AppWindow a XAML Islands. Další informace o verzování naleznete v tématu adaptivní aplikace k verzím .

Ve výchozím nastavení se obsahové dialogy zobrazují modálně vůči kořenové ApplicationView. Při použití ContentDialog uvnitř AppWindow nebo XAML Islandje třeba ručně nastavit XamlRoot v dialogovém okně na kořen hostitele XAML.

K tomu nastavte vlastnost XamlRoot ContentDialogu na stejný XamlRoot jako prvek již v AppWindow nebo XAML Island, jak je znázorněno zde.

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