Dialoogbesturingselementen

Dialoogbesturingselementen zijn modale overlays van de gebruikersinterface die contextuele app-informatie bieden. Ze blokkeren interacties met het app-venster totdat ze expliciet worden gesloten. Ze vragen vaak om een actie van de gebruiker.

Is dit de juiste controle?

Gebruik dialoogvensters om gebruikers op de hoogte te stellen van belangrijke informatie of om bevestiging of aanvullende informatie aan te vragen voordat een actie kan worden voltooid.

Zie Dialoogvensters en flyouts voor aanbevelingen voor het gebruik van een dialoogvenster versus wanneer u een flyout (een vergelijkbaar besturingselement) wilt gebruiken.

Algemene richtlijnen

• Identificeer het probleem duidelijk of het doel van de gebruiker in de eerste regel van de tekst van het dialoogvenster.
• De titel van het dialoogvenster is de hoofdinstructie en is optioneel.
  • Gebruik een korte titel om uit te leggen wat mensen met het dialoogvenster moeten doen.
  • Als u het dialoogvenster gebruikt om een eenvoudig bericht, fout of vraag te geven, kunt u desgewenst de titel weglaten. Vertrouw op de inhoudstekst om die kerninformatie te leveren.
  • Zorg ervoor dat de titel rechtstreeks is gekoppeld aan de knopkeuzes.
• De inhoud van het dialoogvenster bevat de beschrijvende tekst en is vereist.
  • Presenteer de boodschap, fout of blokkerende vraag zo eenvoudig mogelijk.
  • Als een dialoogvenstertitel wordt gebruikt, gebruikt u het inhoudsgebied om meer details te geven of terminologie te definiëren. Herhaal de titel niet met iets andere tekst.
• Er moet ten minste één dialoogvensterknop worden weergegeven.
  • Zorg ervoor dat uw dialoogvenster ten minste één knop bevat die overeenkomt met een veilige, niet-destructieve actie, zoals 'Begrepen!', 'Sluiten' of 'Annuleren'. Gebruik de CloseButton-API om deze knop toe te voegen.
  • Gebruik specifieke antwoorden op de hoofdinstructie of inhoud als knoptekst. Een voorbeeld is 'Wilt u AppName toegang geven tot uw locatie?', gevolgd door de knoppen Toestaan en Blokkeren. Specifieke antwoorden kunnen sneller worden begrepen, wat resulteert in een efficiënte besluitvorming.
  • Zorg ervoor dat de tekst van de actieknoppen beknopt is. Met korte tekenreeksen kan de gebruiker snel en betrouwbaar een keuze maken.
  • Naast de veilige, niet-destructieve actie kunt u de gebruiker eventueel presenteren met een of twee actieknoppen die betrekking hebben op de hoofdinstructie. Met deze uitvoeringsknoppen bevestigen ze de belangrijkste functie van de dialoog. Gebruik de PRIMARYButton- en SecondaryButton-API's om deze 'do it'-acties toe te voegen.
  • De "do it"-actieknop(pen) moeten worden weergegeven als de meest linkse knoppen. De veilige, niet-destructieve actie moet worden weergegeven als de meest rechtse knop.
  • U kunt eventueel een van de drie knoppen onderscheiden als de standaardknop van het dialoogvenster. Gebruik de DefaultButton-API om een van de knoppen te onderscheiden.
• Gebruik geen dialoogvensters voor fouten die contextueel zijn voor een specifieke plaats op de pagina, zoals validatiefouten (in wachtwoordvelden, bijvoorbeeld), gebruik het canvas van de app zelf om inlinefouten weer te geven.
• Gebruik de klasse ContentDialog om uw dialoogvensterervaring te bouwen. Gebruik de afgeschafte MessageDialog-API niet.

Een dialoogvenster maken

De WinUI 3 Gallery-app bevat interactieve voorbeelden van de meeste Besturingselementen, functies en functionaliteit van WinUI 3. Haal de app op uit de Microsoft Store of haal de broncode op GitHub op

Als u een dialoogvenster wilt maken, gebruikt u de klasse ContentDialog. U kunt een dialoog maken in code of opmaak. Hoewel het meestal eenvoudiger is om UI-elementen in XAML te definiëren, kan het in het geval van een eenvoudig dialoogvenster eenvoudiger zijn om alleen code te gebruiken. In dit voorbeeld wordt een dialoogvenster gemaakt om de gebruiker op de hoogte te stellen dat er geen Wi-Fi-verbinding is en wordt vervolgens de methode ShowAsync gebruikt om deze weer te geven.

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

Als uw inhoudsdialoogvenster complexer is, kunt u het eenvoudiger maken met XAML. U kunt het maken in het XAML-bestand voor uw pagina of u kunt een subklasse van ContentDialog maken met het eigen .xaml- en code-behind-bestand. Zie de klassereferentie [ContentDialog] voor volledige voorbeelden van beide.

Er is geen itemsjabloon in Visual Studio om een nieuw inhoudsdialoogvensterbestand te maken, maar u kunt de sjabloon Lege pagina gebruiken en de resulterende bestanden wijzigen om een dialoogvenster te maken.

Een nieuw inhoudsdialoogvenster maken met XAML en code-behind

1. Klik in het deelvenster Solution Explorer met de rechtermuisknop op de projectnaam en selecteer Nieuw item toevoegen > ...
2. Selecteer In het dialoogvenster Nieuw item toevoegenWinUI in de sjabloonlijst aan de linkerkant van het venster.
3. Selecteer het sjabloon Lege pagina.
4. Noem het bestand . (In dit voorbeeld heeft het bestand de naam XamlContentDialog).
5. Druk op Toevoegen.

Wijzig in het nieuwe .xaml-bestand de tags voor het openen en sluiten van pagina's in het dialoogvenster Inhoud.

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

</Page>
-->

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

</ContentDialog>

Maak in het .xaml.cs-bestand uw klasse overgenomen van ContentDialog in plaats van Page.

// public sealed partial class XamlContentDialog : Page

public sealed partial class XamlContentDialog : ContentDialog

Het dialoogvenster weergeven

Als u een dialoogvenster wilt weergeven, roept u de methode ShowAsync aan.

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

De XamlRoot instellen

Wanneer u een ContentDialog weergeeft, moet u de XamlRoot van het dialoogvenster handmatig instellen op de hoofdmap van de XAML-host. Hiervoor stelt u de eigenschap XamlRoot van ContentDialog in op dezelfde XamlRoot als een element in de XAML-structuur.

Als het ContentDialog wordt weergegeven vanaf een pagina, kunt u de eigenschap XamlRoot van ContentDialog instellen op de XamlRoot van de pagina, zoals wordt weergegeven in het vorige voorbeeld.

Het venster heeft geen eigenschap XamlRoot, dus als het dialoogvenster wordt weergegeven vanuit een venster, stelt u de eigenschap XamlRoot van het dialoogvenster in op dat van het hoofdinhoudselement van het venster, zoals hier wordt weergegeven.

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

Reageren op dialoogknoppen

Wanneer de gebruiker op een dialoogvensterknop klikt, retourneert de methode ShowAsync een ContentDialogResult om u te laten weten op welke knop de gebruiker klikt.

In het dialoogvenster in dit voorbeeld wordt een vraag gesteld en wordt het geretourneerde ContentDialogResult gebruikt om het antwoord van de gebruiker te bepalen.

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

Een veilige actie bieden

Omdat dialoogvensters gebruikersinteractie blokkeren en omdat knoppen het primaire mechanisme zijn voor gebruikers om het dialoogvenster te sluiten, moet u ervoor zorgen dat uw dialoogvenster ten minste één 'veilige' en niet-destructieve knop bevat, zoals 'Sluiten' of 'Ophalen!'. Alle dialoogvensters moeten ten minste één veilige actieknop bevatten om het dialoogvenster te sluiten. Dit zorgt ervoor dat de gebruiker het dialoogvenster met vertrouwen kan sluiten zonder een actie uit te voeren.

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

Wanneer dialoogvensters worden gebruikt om een blokkeringsvraag weer te geven, moet de gebruiker in het dialoogvenster actieknoppen met betrekking tot de vraag worden weergegeven. De "veilige" en niet-destructieve knop kan vergezeld gaan van een of twee "doe het" actieknoppen. Wanneer u de gebruiker met meerdere opties presenteert, moet u ervoor zorgen dat de knoppen duidelijk de acties 'doe het doen' en veilig/'niet doen' uitleggen met betrekking tot de voorgestelde vraag.

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

Er worden drie knopdialoogvensters gebruikt wanneer u de gebruiker met twee 'doe het'-acties en een actie 'niet doen' presenteert. Drie knopdialoogvensters moeten spaarzaam worden gebruikt met duidelijk onderscheid tussen de secundaire actie en de actie veilig/sluiten.

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

ContentDialog heeft drie verschillende typen knoppen die u kunt gebruiken om een dialoogvenster te maken.

• CloseButton - Vereist - Vertegenwoordigt de veilige, niet-destructieve actie waarmee de gebruiker het dialoogvenster kan afsluiten. Wordt weergegeven als de meest rechtse knop.
• PrimaryButton - Optioneel - Vertegenwoordigt de eerste actie 'doe het'. Wordt weergegeven als de meest linkse knop.
• SecondaryButton - Optioneel - Vertegenwoordigt de tweede actie 'doe het'. Wordt weergegeven als de middelste knop.

Als u de ingebouwde knoppen gebruikt, worden de knoppen op de juiste wijze geplaatst, zorgt u ervoor dat ze correct reageren op toetsenbordgebeurtenissen, ervoor zorgen dat het opdrachtgebied zichtbaar blijft, zelfs wanneer het schermtoetsenbord is ingeschakeld en het dialoogvenster consistent is met andere dialoogvensters.

Sluitknop

Elk dialoogvenster moet een veilige, niet-destructieve actieknop bevatten waarmee de gebruiker het dialoogvenster kan afsluiten.

Gebruik de ContentDialog.CloseButton-API om deze knop te maken. Hiermee kunt u de juiste gebruikerservaring maken voor alle invoerwaarden, waaronder muis, toetsenbord, aanraakscherm en gamepad. Deze ervaring treedt op wanneer:

• De gebruiker klikt of tikt op de CloseButton.
• De gebruiker drukt op de systeemterugknop.
• De gebruiker drukt op de esc-knop op het toetsenbord.
• De gebruiker drukt op Gamepad B.

Wanneer de gebruiker op een dialoogvensterknop klikt, retourneert de methode ShowAsync een ContentDialogResult om u te laten weten op welke knop de gebruiker klikt. Als u op CloseButton drukt, wordt ContentDialogResult.None geretourneerd.

PrimaryButton en SecondaryButton

Naast de CloseButton kunt u de gebruiker eventueel presenteren met een of twee actieknoppen die betrekking hebben op de hoofdinstructie. Maak gebruik van PrimaryButton voor de eerste actie 'doe het' en SecondaryButton voor de tweede 'doe het'-actie. In dialoogvensters met drie knoppen vertegenwoordigt de PrimaryButton over het algemeen de bevestigende "do it" actie, terwijl de SecondaryButton over het algemeen een neutrale of secundaire "do it" actie vertegenwoordigt. Een app kan bijvoorbeeld de gebruiker vragen zich te abonneren op een service. De primairebutton als de bevestigende actie "doe het" zou als host fungeren voor de tekst Abonneren, terwijl de SecundaireButton als de neutrale actie 'doe het' de tekst Proberen zou hosten. Met CloseButton kan de gebruiker annuleren zonder een van de acties uit te voeren.

Wanneer de gebruiker op PrimaryButton klikt, retourneert de methode ShowAsync ContentDialogResult.Primary. Wanneer de gebruiker op secondaryButton klikt, retourneert de methode ShowAsync ContentDialogResult.Secondary.

Standaardknop

U kunt er desgewenst voor kiezen om een van de drie knoppen te onderscheiden als de standaardknop. Als u de standaardknop instelt, gebeurt het volgende:

• De knop ontvangt de visuele behandeling van de accentknop
• De knop reageert automatisch op de ENTER-toets
  • Wanneer de gebruiker op de Enter-toets op het toetsenbord drukt, wordt de klikhandler die is gekoppeld aan de standaardknop geactiveerd en retourneert ContentDialogResult de waarde die is gekoppeld aan de standaardknop
  • Als de gebruiker toetsenbordfocus heeft geplaatst op een besturingselement dat ENTER verwerkt, reageert de standaardknop niet op Enter
• De knop krijgt automatisch de focus wanneer het dialoogvenster wordt geopend, tenzij de inhoud van het dialoogvenster focusbare elementen bevat.

Gebruik de eigenschap ContentDialog.DefaultButton om de standaardknop aan te geven. Standaard is er geen standaardknop ingesteld.

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

Bevestigingsdialoogvensters (OK/Annuleren)

Een bevestigingsdialoogvenster geeft gebruikers de mogelijkheid om te bevestigen dat ze een actie willen uitvoeren. Ze kunnen de actie bevestigen of ervoor kiezen om te annuleren. Een typisch bevestigingsvenster heeft twee knoppen: een bevestigingsknop ('OK') en een knop Annuleren.

• Over het algemeen moet de bevestigingsknop aan de linkerkant (de primaire knop) en de knop Annuleren (de secundaire knop) rechts staan.

  
• Zoals vermeld in de sectie algemene aanbevelingen, gebruikt u knoppen met tekst die specifieke antwoorden op de hoofdinstructie of inhoud identificeert.

UWP en WinUI 2

API's voor deze controle bevinden zich in de naamruimte Windows.UI.Xaml.Controls.

U wordt aangeraden de nieuwste WinUI 2 te gebruiken om de meest recente stijlen en sjablonen voor alle besturingselementen te verkrijgen. WinUI 2.2 of hoger bevat een nieuwe sjabloon voor dit besturingselement dat gebruikmaakt van afgeronde hoeken. Zie Hoekstraal voor meer informatie.

ContentDialog in AppWindow- of Xaml-eilanden

OPMERKING: deze sectie is alleen van toepassing op apps die gericht zijn op Windows 10, versie 1903 of hoger. AppWindow en XAML-eilanden zijn niet beschikbaar in eerdere versies. Zie Adaptieve versie-apps voor meer informatie over versiebeheer.

Standaard worden inhoudsdialoogvensters modaal ten opzichte van de hoofdtoepassingsweergave weergegeven. Wanneer u ContentDialog in een AppWindow of een XAML-eiland gebruikt, moet u de XamlRoot in het dialoogvenster handmatig instellen op de hoofdmap van de XAML-host.

Hiervoor stelt u de eigenschap XamlRoot van ContentDialog in op dezelfde XamlRoot als een element dat al aanwezig is in het AppWindow- of XAML-eiland, zoals hier wordt weergegeven.

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

Verwante artikelen

• Tooltip
• Menus en contextmenu
• Flyout-klasse
• Klasse ContentDialog