Dialogkontroller

Dialogkontroller är modala gränssnittsöverlägg som ger sammanhangsberoende appinformation. De blockerar interaktioner med appfönstret tills de uttryckligen avvisas. De begär ofta någon form av åtgärd från användaren.

Exempel på en dialogruta

Är det här rätt kontroll?

Använd dialogrutor för att meddela användarna om viktig information eller för att begära bekräftelse eller ytterligare information innan en åtgärd kan slutföras.

Rekommendationer om när du ska använda en dialogruta jämfört med när du ska använda ett utvik (en liknande kontroll) finns i Dialogrutor och Utvik.

Allmänna riktlinjer

Identifiera problemet eller användarens mål tydligt på den första raden i dialogrutans text.
Dialogrutans rubrik är huvudinstruktionen och är valfri.
- Använd en kort rubrik för att förklara vad personer behöver göra med dialogrutan.
- Om du använder dialogrutan för att leverera ett enkelt meddelande, ett fel eller en fråga kan du eventuellt utelämna rubriken. Förlita dig på innehållstexten för att leverera den grundläggande informationen.
- Kontrollera att rubriken är direkt kopplad till knappvalen.
Dialoginnehållet innehåller den beskrivande texten och krävs.
- Presentera meddelandet, felet eller blockeringsfrågan så enkelt som möjligt.
- Om en dialogrubrik används använder du innehållsområdet för att ange mer information eller definiera terminologi. Upprepa inte rubriken med något annorlunda formulering.
Minst en dialogruta måste visas.
- Kontrollera att dialogrutan har minst en knapp som motsvarar en säker, icke-förstörande åtgärd som "Got it!", "Close" eller "Cancel". Använd CloseButton-API:et för att lägga till den här knappen.
- Använd specifika svar på huvudinstruktionen eller innehållet som knapptext. Ett exempel är "Vill du tillåta att AppName får åtkomst till din plats?", följt av knapparna "Tillåt" och "Blockera". Specifika svar kan förstås snabbare, vilket resulterar i ett effektivt beslutsfattande.
- Kontrollera att texten i åtgärdsknapparna är koncis. Med korta strängar kan användaren snabbt och säkert välja.
- Förutom den säkra, icke-förstörande åtgärden kan du eventuellt presentera användaren med en eller två åtgärdsknappar relaterade till huvudinstruktionen. Dessa "gör det"-åtgärdsknappar bekräftar den viktigaste punkten i dialogrutan. Använd API:erna PrimaryButton och SecondaryButton för att lägga till dessa "gör det"-åtgärder.
- Åtgärdsknapparna "gör det" ska visas som knapparna längst till vänster. Den säkra, icke-förstörande åtgärden bör visas som knappen längst till höger.
- Du kan välja att särskilja en av de tre knapparna som dialogrutans standardknapp. Använd DefaultButton-API:et för att särskilja en av knapparna.
Använd inte dialogrutor för fel som är kontextuella för en specifik plats på sidan, till exempel valideringsfel (i lösenordsfält, till exempel), utan använd själva appens arbetsyta för att visa infogade fel.
Använd klassen ContentDialog för att skapa din dialogupplevelse. Använd inte det inaktuella MessageDialog-API:et.

Skapa en dialogruta

Viktiga API:er: ContentDialog-klass

Öppna WinUI-galleriappen och se ContentDialog i praktiken

Med WinUI 3-galleriappen kan du utforska och bläddra bland interaktiva exempel på WinUI 3-kontroller, funktioner och funktioner. Hämta appen från Microsoft Store eller hämta källkoden på GitHub.

Om du vill skapa en dialogruta använder du klassen ContentDialog. Du kan skapa en dialogruta i kod eller markering. Även om det vanligtvis är enklare att definiera användargränssnittselement i XAML, kan det i en enkel dialogruta vara enklare att bara använda kod. Det här exemplet skapar en dialogruta för att meddela användaren att det inte finns någon WiFi-anslutning och använder sedan metoden ShowAsync för att visa den.

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

Om innehållsdialogrutan är mer komplex kan det vara enklare att skapa den med XAML. Du kan antingen skapa den i XAML-filen för din sida eller skapa en underklass av ContentDialog med en egen .xaml-fil och en egen code-behind-fil. Fullständiga exempel på båda finns i klassreferensen [ContentDialog].

Det finns ingen objektmall i Visual Studio för att skapa en ny innehållsdialogfil, men du kan använda mallen Tom sida och ändra de resulterande filerna för att skapa en dialogruta.

Skapa en ny innehållsdialogruta med XAML och bakomliggande kod

I fönstret Solution Explorer högerklickar du på projektnamnet och väljer Lägg till > nytt objekt...
I dialogrutan Lägg till nytt objekt väljer du WinUI i malllistan till vänster i fönstret.
Välj mallen Tom sida .
Ge filen namnet . (I det här exemplet heter XamlContentDialogfilen ).
Tryck på Lägg till.

I den nya .xaml-filen ändrar du taggarna för att öppna och stänga sidan till Innehållsdialogruta.

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

</Page>
-->

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

</ContentDialog>

I filen .xaml.cs ska din klass ärva från ContentDialog istället för Sida.

// public sealed partial class XamlContentDialog : Page

public sealed partial class XamlContentDialog : ContentDialog

Visa dialogrutan

Om du vill visa en dialogruta anropar du metoden ShowAsync .

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

Varning

Det kan bara finnas en ContentDialog öppen per fönster i taget. Om du försöker öppna två innehållsdialogrutor utlöser du ett undantag.

Ange XamlRoot

När du visar en ContentDialog måste du manuellt ange XamlRoot för dialogrutan till XAML-värdens rot. Det gör du genom att ange egenskapen XamlRoot för ContentDialog till samma XamlRoot som ett element som redan finns i XAML-trädet.

Om en sida visar ContentDialog kan du ange egenskapen XamlRoot för ContentDialog till sidans XamlRoot enligt föregående exempel.

Fönstret har ingen XamlRoot-egenskap, så om dialogrutan visas från ett fönster anger du dialogrutans XamlRoot-egenskap till egenskapen för fönstrets rotinnehållselement, som visas här.

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

Svara på dialogknappar

När användaren klickar på en dialogruta returnerar metoden ShowAsync en ContentDialogResult- så att du vet vilken knapp användaren klickar på.

Dialogrutan i det här exemplet ställer en fråga och använder den returnerade ContentDialogResult för att fastställa användarens svar.

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

Tillhandahålla en säker åtgärd

Eftersom dialogrutor blockerar användarinteraktion och eftersom knappar är den primära mekanismen för användare att stänga dialogrutan kontrollerar du att dialogrutan innehåller minst en "säker" och icke-förstörande knapp, till exempel "Stäng" eller "Got it!". Alla dialogrutor bör innehålla minst en knapp för säker åtgärd för att stänga dialogrutan. Detta säkerställer att användaren säkert kan stänga dialogrutan utan att utföra en åtgärd.

En dialogruta med en knapp

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

När dialogrutor används för att visa en blockerande fråga bör din dialogruta presentera användaren med åtgärdsknappar relaterade till frågan. Den "säkra" och icke-förstörande knappen kan åtföljas av en eller två åtgärdsknappar för "gör det". När du presenterar användaren med flera alternativ ska du se till att knapparna tydligt förklarar åtgärderna "do it" och safe/"don't do it" relaterade till den föreslagna frågan.

En dialogruta med två knappar

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

Tre knappdialogrutor används när du presenterar användaren med två "gör det"-åtgärder och en "gör det inte"-åtgärd. Tre knappdialogrutor ska användas sparsamt med tydliga distinktioner mellan den sekundära åtgärden och säker/stäng-åtgärden.

En dialogruta med tre knappar

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

De tre dialogknapparna

ContentDialog har tre olika typer av knappar som du kan använda för att skapa en dialogupplevelse.

CloseButton – Krävs – Representerar den säkra, icke-förstörande åtgärden som gör att användaren kan avsluta dialogrutan. Visas som knappen längst till höger.
PrimaryButton – Valfritt – Representerar den första åtgärden "gör det". Visas som knappen längst till vänster.
SecondaryButton – Valfritt – Representerar den andra åtgärden "gör det". Visas som mittenknappen.

Med hjälp av de inbyggda knapparna placeras knapparna på rätt sätt, ser till att de svarar korrekt på tangentbordshändelser, ser till att kommandoområdet förblir synligt även när skärmtangentbordet är uppe och gör att dialogrutan ser konsekvent ut med andra dialogrutor.

Stäng-knapp

Varje dialogruta ska innehålla en säker, icke-förstörande åtgärdsknapp som gör det möjligt för användaren att avsluta dialogrutan på ett säkert sätt.

Använd API:et ContentDialog.CloseButton för att skapa den här knappen. På så sätt kan du skapa rätt användarupplevelse för alla indata, inklusive mus, tangentbord, touch och gamepad. Den här upplevelsen inträffar när:

Användaren klickar eller trycker på CloseButton.
Användaren trycker på tillbaka-knappen för systemet.
Användaren trycker på ESC-knappen på tangentbordet.
Användaren trycker på Gamepad B.

När användaren klickar på en dialogruta returnerar metoden ShowAsync en ContentDialogResult- så att du vet vilken knapp användaren klickar på. Om du trycker på CloseButton returneras ContentDialogResult.None.

Primärknapp och Sekundärknapp

Förutom CloseButton kan du eventuellt presentera användaren med en eller två åtgärdsknappar relaterade till huvudinstruktionen. Använd PrimaryButton för den första åtgärden "gör det" och SecondaryButton för den andra åtgärden "gör det". I dialogrutor med tre knappar representerar PrimaryButton vanligtvis den positiva åtgärden "gör det", medan SecondaryButton vanligtvis representerar en neutral eller sekundär "gör det"-åtgärd. En app kan till exempel uppmana användaren att prenumerera på en tjänst. Primärknappen som den bekräftande åtgärden "gör det" skulle vara värd för "Subscribe"-texten, medan Sekundärknappen som den neutrala åtgärden "gör det" skulle vara värd för "Prova det"-texten. CloseButton skulle göra det möjligt för användaren att avbryta utan att utföra någon av åtgärderna.

När användaren klickar på PrimaryButton returnerar metoden ShowAsync ContentDialogResult.Primary. När användaren klickar på SecondaryButton returnerar metoden ShowAsync ContentDialogResult.Secondary.

En dialogruta med tre knappar

Standardknapp

Du kan välja att särskilja en av de tre knapparna som standardknapp. Om du anger standardknappen händer följande:

Knappen får den visuella utformningen för Accent Button
Knappen svarar automatiskt på RETUR-tangenten
- När användaren trycker på RETUR-tangenten på tangentbordet utlöses klickhanteraren som är associerad med standardknappen och ContentDialogResult returnerar värdet som är associerat med standardknappen
- Om användaren har placerat tangentbordsfokus på en kontroll som hanterar RETUR svarar inte standardknappen på RETUR-tryckningar
Knappen får fokus automatiskt när dialogrutan öppnas om inte dialogrutans innehåll innehåller ett fokuserbart användargränssnitt

Använd egenskapen ContentDialog.DefaultButton för att ange standardknappen. Som standard anges ingen standardknapp.

En dialogruta med tre knappar med en standardknapp

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

Bekräftelsedialoger (OK/Avbryt)

En bekräftelsedialogruta ger användarna möjlighet att bekräfta att de vill utföra en åtgärd. De kan bekräfta åtgärden eller välja att avbryta. En typisk bekräftelsedialogruta har två knappar: en bekräftelseknapp ("OK") och en avbryt-knapp.

I allmänhet ska bekräftelseknappen vara till vänster (den primära knappen) och knappen Avbryt (den sekundära knappen) ska vara till höger.
Som du ser i avsnittet allmänna rekommendationer använder du knappar med text som identifierar specifika svar på huvudinstruktionen eller innehållet.

ContentDialog i AppWindow eller Xaml Islands

Obs! Det här avsnittet gäller endast för appar som är avsedda för Windows 10, version 1903 eller senare. AppWindow- och XAML-öarna är inte tillgängliga i tidigare versioner. Mer information om versionshantering finns i Version av anpassningsbara appar.

Som standard visas innehållsdialogrutorna modalt i förhållande till roten ApplicationView. När du använder ContentDialog i antingen en AppWindow eller en XAML Island, måste du manuellt ställa in XamlRoot på dialogrutan till XAML-värdens rot.

För att göra det anger du egenskapen XamlRoot för ContentDialog till samma XamlRoot som ett element som redan finns i AppWindow eller XAML Island, som du ser här.

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