Contrôles de boîte de dialogueDialog controls

Les contrôles de boîtes de dialogue sont des superpositions d’interface utilisateur modales qui fournissent des informations contextuelles sur l’application.Dialog controls are modal UI overlays that provide contextual app information. Ils bloquent les interactions avec la fenêtre de l’application jusqu’à ce qu’elles soient masquées explicitement.They block interactions with the app window until being explicitly dismissed. Elles exigent souvent une forme d’action de la part de l’utilisateur.They often request some kind of action from the user.

Exemple de boîte de dialogue

Obtenir la bibliothèque d’interface utilisateur WindowsGet the Windows UI Library

Logo WinUI

La bibliothèque d’interface utilisateur Windows version 2.2 ou ultérieure inclut pour ce contrôle un nouveau modèle qui utilise des angles arrondis.Windows UI Library 2.2 or later includes a new template for this control that uses rounded corners. Pour plus d’informations, consultez Rayons des angles.For more info, see Corner radius. WinUI est un package NuGet qui contient de nouveaux contrôles et des fonctionnalités d’interface utilisateur pour les applications Windows.WinUI is a NuGet package that contains new controls and UI features for Windows apps. Pour plus d’informations, notamment des instructions d’installation, consultez la bibliothèque d’interface utilisateur Windows.For more info, including installation instructions, see Windows UI Library.

API de plateforme : Classe ContentDialogPlatform APIs: ContentDialog class

Est-ce le contrôle approprié ?Is this the right control?

Utilisez les boîtes de dialogue pour notifier les utilisateurs d’informations importantes ou pour demander une confirmation ou des informations supplémentaires avant de pouvoir effectuer une action.Use dialogs to notify users of important information or to request confirmation or additional info before an action can be completed.

Pour savoir quand utiliser une boîte de dialogue ou un menu volant (contrôle similaire), consultez Boîtes de dialogue et menus volants.For recommendations on when to use a dialog vs. when to use a flyout (a similar control), see Dialogs and flyouts.

ExemplesExamples

Galerie de contrôles XAMLXAML Controls Gallery
XAML controls gallery

Si vous disposez de l’application Galerie de contrôles XAML, cliquez ici pour ouvrir l’application et voir l’objet ContentDialog ou Flyout en action.If you have the XAML Controls Gallery app installed, click here to open the app and see the ContentDialog or Flyout in action.

Recommandations généralesGeneral guidelines

  • Identifiez clairement le problème ou l’objectif de l’utilisateur dans la première ligne du texte de la boîte de dialogue.Clearly identify the issue or the user's objective in the first line of the dialog's text.
  • Le titre de la boîte de dialogue correspond à l’instruction principale. Il est facultatif.The dialog title is the main instruction and is optional.
    • Utilisez un titre court pour expliquer l’utilisation de cette boîte de dialogue.Use a short title to explain what people need to do with the dialog.
    • Si la boîte de dialogue est destinée à indiquer un message, une erreur ou une question simple, vous pouvez ne pas indiquer de titre.If you're using the dialog to deliver a simple message, error or question, you can optionally omit the title. Appuyez-vous sur le texte du contenu pour fournir les informations essentielles.Rely on the content text to deliver that core information.
    • Assurez-vous que le titre est directement lié aux options des boutons.Make sure that the title relates directly to the button choices.
  • Le contenu de la boîte de dialogue inclut le texte descriptif. Il est requis.The dialog content contains the descriptive text and is required.
    • Présentez le message, l’erreur ou la question bloquante aussi simplement que possible.Present the message, error, or blocking question as simply as possible.
    • Si vous indiquez un titre dans la boîte de dialogue, la zone de contenu doit fournir des détails supplémentaires ou clarifier la terminologie utilisée.If a dialog title is used, use the content area to provide more detail or define terminology. Ne répétez pas le titre en utilisant une formulation légèrement différente.Don't repeat the title with slightly different wording.
  • Au moins un bouton de boîte de dialogue doit apparaître.At least one dialog button must appear.
    • Assurez-vous que votre boîte de dialogue dispose d’au moins un bouton correspondant à une action sans échec, non destructrice, par exemple : « D’accord ! », « Fermer » ou « Annuler ».Ensure that your dialog has at least one button corresponding to a safe, nondestructive action like "Got it!", "Close", or "Cancel". Utilisez l’API CloseButton pour ajouter ce bouton.Use the CloseButton API to add this button.
    • Utilisez des réponses spécifiques du contenu ou de l’instruction principale, sous forme de texte de bouton.Use specific responses to the main instruction or content as button text. Par exemple, utilisez la question « Autorisez-vous NomApplication à accéder à votre emplacement ? », suivie des boutons Autoriser et Bloquer.An example is, "Do you want to allow AppName to access your location?", followed by "Allow" and "Block" buttons. Les réponses spécifiques peuvent être comprises plus rapidement, ce qui favorise une prise de décision efficace.Specific responses can be understood more quickly, resulting in efficient decision making.
    • Veillez à ce que le texte des boutons d’action soit concis.Ensure that the text of the action buttons is concise. Les chaînes courtes permettent à l’utilisateur de choisir de manière sûre et rapide.Short strings enable the user to make a choice quickly and confidently.
    • En plus de l’action sans échec et non destructrice, vous pouvez éventuellement présenter à l’utilisateur un ou deux boutons d’action liés à l’instruction principale.In addition to the safe, nondestructive action, you may optionally present the user with one or two action buttons related to the main instruction. Ces boutons d’action « faire » confirment le message principal de la boîte de dialogue.These "do it" action buttons confirm the main point of the dialog. Utilisez les API PrimaryButton et SecondaryButton pour ajouter ces actions « faire ».Use the PrimaryButton and SecondaryButton APIs to add these "do it" actions.
    • Les boutons d’action « faire » doivent s’afficher à l’extrême gauche.The "do it" action button(s) should appear as the leftmost buttons. L’action sans échec et non destructrice doit s’afficher à l’extrême droite.The safe, nondestructive action should appear as the rightmost button.
    • Vous pouvez éventuellement choisir de différencier l’un des trois boutons comme bouton par défaut de la boîte de dialogue.You may optionally choose to differentiate one of the three buttons as the dialog's default button. Utilisez l’API DefaultButton pour différencier l’un des boutons.Use the DefaultButton API to differentiate one of the buttons.
  • N’utilisez pas de boîtes de dialogue pour les erreurs qui sont liées à un emplacement spécifique de la page, telles que les erreurs de validation (dans les champs de mot de passe, par exemple). Utilisez plutôt le canevas de l’application afin d’afficher les erreurs insérées.Don't use dialogs for errors that are contextual to a specific place on the page, such as validation errors (in password fields, for example), use the app's canvas itself to show inline errors.
  • Utilisez la classe ContentDialog pour créer votre expérience de boîte de dialogue.Use the ContentDialog class to build your dialog experience. N’utilisez pas l’API MessageDialog déconseillée.Don't use the deprecated MessageDialog API.

Procédure pour créer une boîte de dialogueHow to create a dialog

Pour créer une boîte de dialogue, vous utilisez la classe ContentDialog.To create a dialog, you use the ContentDialog class. Vous pouvez créer une boîte de dialogue dans le code ou dans le balisage.You can create a dialog in code or markup. Bien qu’il soit généralement plus facile de définir des éléments d’interface utilisateur en XAML, dans le cas d’une boîte de dialogue simple, il est plus facile d’utiliser du code normal.Although its usually easier to define UI elements in XAML, in the case of a simple dialog, it's actually easier to just use code. Cet exemple crée une boîte de dialogue pour informer l’utilisateur qu’il n’y a pas de connexion Wi-Fi, puis utilise la méthode ShowAsync pour l’afficher.This example creates a dialog to notify the user that there's no WiFi connection, and then uses the ShowAsync method to display it.

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

Quand l’utilisateur clique sur un bouton de la boîte de dialogue, la méthode ShowAsync retourne un ContentDialogResult pour indiquer le bouton sur lequel l’utilisateur clique.When the user clicks a dialog button, the ShowAsync method returns a ContentDialogResult to let you know which button the user clicks.

Dans cet exemple, la boîte de dialogue pose une question et utilise le ContentDialogResult retourné pour déterminer la réponse de l’utilisateur.The dialog in this example asks a question and uses the returned ContentDialogResult to determine the user's response.

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

Fournir une action sans échecProvide a safe action

Étant donné que les boîtes de dialogue bloquent les interactions des utilisateurs et dans la mesure où les boutons sont le principal mécanisme permettant aux utilisateurs d’ignorer la boîte de dialogue, assurez-vous que votre boîte de dialogue contient au moins un bouton « sans échec » et non destructeur, tel que « Fermer » ou « D’accord ! ».Because dialogs block user interaction, and because buttons are the primary mechanism for users to dismiss the dialog, ensure that your dialog contains at least one "safe" and nondestructive button such as "Close" or "Got it!". Toutes les boîtes de dialogue doivent contenir au moins un bouton d’action sans échec permettant de fermer la boîte de dialogue.All dialogs should contain at least one safe action button to close the dialog. Cela garantit que l’utilisateur peut fermer la boîte de dialogue en toute confiance, sans effectuer d’action.This ensures that the user can confidently close the dialog without performing an action.
Une boîte de dialogue à un boutonAn one button dialog

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

Lorsque les boîtes de dialogue sont utilisées pour afficher une question bloquante, votre boîte de dialogue doit proposer à l’utilisateur des boutons d’action liés à la question.When dialogs are used to display a blocking question, your dialog should present the user with action buttons related to the question. Le bouton « sans échec » et non destructeur peut s’accompagner d’un ou deux boutons d’action « faire ».The "safe" and nondestructive button may be accompanied by one or two "do it" action buttons. Lorsque vous proposez plusieurs options à l’utilisateur, assurez-vous que les boutons expliquent clairement les actions sans échec « faire » et « ne pas faire » liées à la question proposée.When presenting the user with multiple options, ensure that the buttons clearly explain the "do it" and safe/"don't do it" actions related to the question proposed.

Une boîte de dialogue à deux boutons

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

Les boîtes de dialogue à trois boutons sont utilisées lorsque vous proposez à l’utilisateur deux actions « faire » et une action « ne pas faire ».Three button dialogs are used when you present the user with two "do it" actions and a "don't do it" action. Les boîtes de dialogue à trois boutons doivent être utilisées avec parcimonie, en distinguant clairement l’action secondaire et l’action sans échec/fermer.Three button dialogs should be used sparingly with clear distinctions between the secondary action and the safe/close action.

Une boîte de dialogue à trois boutons

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

Les trois boutons de la boîte de dialogueThe three dialog buttons

ContentDialog présente trois différents types de boutons que vous pouvez utiliser pour créer une expérience de boîte de dialogue.ContentDialog has three different types of buttons that you can use to build a dialog experience.

  • CloseButton - Requis - Représente l’action sans échec et non destructrice qui permet à l’utilisateur de fermer la boîte de dialogue.CloseButton - Required - Represents the safe, nondestructive action that enables the user to exit the dialog. S’affiche comme bouton à l’extrême droite.Appears as the rightmost button.
  • PrimaryButton - Facultatif - Représente la première action « faire ».PrimaryButton - Optional - Represents the first "do it" action. S’affiche comme bouton à l’extrême gauche.Appears as the leftmost button.
  • SecondaryButton - Facultatif - Représente la seconde action « faire ».SecondaryButton - Optional - Represents the second "do it" action. S’affiche comme bouton du milieu.Appears as the middle button.

L’utilisation des boutons intégrés positionne les boutons de manière adéquate. Assurez-vous qu’ils répondent aux événements de clavier, que la zone de commande reste visible même lorsque le clavier visuel est affiché, et qu’ils offrent à la boîte de dialogue une apparence cohérente avec les autres boîtes de dialogue.Using the built-in buttons will position the buttons appropriately, ensure that they correctly respond to keyboard events, ensure that the command area remains visible even when the on-screen keyboard is up, and will make the dialog look consistent with other dialogs.

CloseButtonCloseButton

Chaque boîte de dialogue doit contenir un bouton d’action sans échec et non destructeur qui permet à l’utilisateur de fermer la boîte de dialogue en toute confiance.Every dialog should contain a safe, nondestructive action button that enables the user to confidently exit the dialog.

Utilisez l’API ContentDialog.CloseButton pour créer ce bouton.Use the ContentDialog.CloseButton API to create this button. Cela vous permet de créer l’expérience utilisateur adéquate pour toutes les entrées, notamment souris, clavier, interaction tactile et boîtier de commande.This allows you to create the right user experience for all inputs including mouse, keyboard, touch, and gamepad. Cette expérience se produit dans les cas suivants :This experience will happen when:

  1. L’utilisateur clique ou appuie sur le CloseButtonThe user clicks or taps on the CloseButton
  2. L’utilisateur appuie sur le bouton Précédent du systèmeThe user presses the system back button
  3. L’utilisateur appuie sur la touche ÉCHAP du clavierThe user presses the ESC button on the keyboard
  4. L’utilisateur appuie sur bouton B du boîtier de commandeThe user presses Gamepad B

Quand l’utilisateur clique sur un bouton de la boîte de dialogue, la méthode ShowAsync retourne un ContentDialogResult pour indiquer le bouton sur lequel l’utilisateur clique.When the user clicks a dialog button, the ShowAsync method returns a ContentDialogResult to let you know which button the user clicks. Le fait d’appuyer sur le CloseButton renvoie ContentDialogResult.None.Pressing on the CloseButton returns ContentDialogResult.None.

PrimaryButton et SecondaryButtonPrimaryButton and SecondaryButton

Outre CloseButton, vous pouvez éventuellement proposer à l’utilisateur un ou deux boutons d’action liés à l’instruction principale.In addition to the CloseButton, you may optionally present the user with one or two action buttons related to the main instruction. Tirez parti de PrimaryButton pour la première action « faire » et SecondaryButton pour la seconde action « faire ».Leverage PrimaryButton for the first "do it" action, and SecondaryButton for the second "do it" action. Dans les boîtes de dialogue à trois boutons, le PrimaryButton représente généralement l’action « faire » positive, tandis que le SecondaryButton représente généralement une action « faire » neutre ou secondaire.In three-button dialogs, the PrimaryButton generally represents the affirmative "do it" action, while the SecondaryButton generally represents a neutral or secondary "do it" action. Par exemple, une application peut inviter l’utilisateur à s’abonner à un service.For example, an app may prompt the user to subscribe to a service. En tant qu’action « faire » affirmative, PrimaryButton intégrerait le texte S’abonner, alors qu’en tant qu’action « faire » neutre, le SecondaryButton intégrerait le texte Essayer.The PrimaryButton as the affirmative "do it" action would host the Subscribe text, while the SecondaryButton as the neutral "do it" action would host the Try it text. CloseButton permettrait à l’utilisateur d’annuler sans effectuer l’une ou l’autre des actions.The CloseButton would allow the user to cancel without performing either action.

Lorsque l’utilisateur clique sur le PrimaryButton, la méthode ShowAsync renvoie ContentDialogResult.Primary.When the user clicks on the PrimaryButton, the ShowAsync method returns ContentDialogResult.Primary. Lorsque l’utilisateur clique sur le SecondaryButton, la méthode ShowAsync renvoie ContentDialogResult.Secondary.When the user clicks on the SecondaryButton, the ShowAsync method returns ContentDialogResult.Secondary.

Une boîte de dialogue à trois boutons

DefaultButtonDefaultButton

Vous pouvez éventuellement choisir de différencier l’un des trois boutons comme bouton par défaut.You may optionally choose to differentiate one of the three buttons as the default button. La spécification d’un bouton par défaut déclenche les événements suivants :Specifying the default button causes the following to happen:

  • Le bouton reçoit le traitement visuel du bouton d’accentThe button receives the Accent Button visual treatment
  • Le bouton répond automatiquement à la touche ENTRÉEThe button will respond to the ENTER key automatically
    • Lorsque l’utilisateur appuie sur la touche ENTRÉE du clavier, le gestionnaire d’événements de clic associé au bouton par défaut se déclenche et ContentDialogResult renvoie la valeur associée au bouton par défautWhen the user presses the ENTER key on the keyboard, the click handler associated with the Default Button will fire and the ContentDialogResult will return the value associated with the Default Button
    • Si l’utilisateur a placé le focus du clavier sur un contrôle qui gère la touche ENTRÉE, le bouton par défaut ne répond pas aux appuis sur ENTRÉEIf the user has placed Keyboard Focus on a control that handles ENTER, the Default Button will not respond to ENTER presses
  • Le bouton reçoit automatiquement le focus lors de l’ouverture de la boîte de dialogue, sauf si le contenu de la boîte de dialogue contient une interface utilisateur pouvant être activeThe button will receive focus automatically when the Dialog is opened unless the dialog's content contains focusable UI

Utilisez la propriété ContentDialog.DefaultButton pour spécifier le bouton par défaut.Use the ContentDialog.DefaultButton property to indicate the default button. Par défaut, aucun bouton par défaut n’est défini.By default, no default button is set.

Une boîte de dialogue à trois boutons avec un bouton par défaut

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

Boîtes de dialogue de confirmation (OK/Annuler)Confirmation dialogs (OK/Cancel)

Une boîte de dialogue de confirmation permet aux utilisateurs de confirmer qu’ils souhaitent effectuer une action.A confirmation dialog gives users the chance to confirm that they want to perform an action. Ils peuvent confirmer l’action ou l’annuler.They can affirm the action, or choose to cancel. Une boîte de dialogue de confirmation classique comprend deux boutons : un bouton d’affirmation (« OK ») et un bouton d’annulation.A typical confirmation dialog has two buttons: an affirmation ("OK") button and a cancel button.

  • En règle générale, le bouton d’affirmation doit se trouver sur la gauche (bouton principal) et le bouton Annuler (bouton secondaire) sur la droite.In general, the affirmation button should be on the left (the primary button) and the cancel button (the secondary button) should be on the right.

    An OK/cancel dialog
  • Comme indiqué dans la section Recommandations générales, utilisez des boutons dont le texte identifie des réponses spécifiques au contenu ou à l’instruction principale.As noted in the general recommendations section, use buttons with text that identifies specific responses to the main instruction or content.

Certaines plateformes placent le bouton d’affirmation à droite, et non à gauche.Some platforms put the affirmation button on the right instead of the left. Pourquoi est-il conseillé de le placer sur la gauche ?So why do we recommend putting it on the left? Si vous partons du principe que la plupart des utilisateurs sont droitiers et qu’ils tiennent leur téléphone de la main droite, ils trouveront certainement plus confortable d’appuyer sur le bouton lorsqu’il se trouve à gauche, autrement dit dans le prolongement du pouce. Les boutons placés à droite de l’écran obligent l’utilisateur à enfoncer son pouce, ce qui est moins confortable.If you assume that the majority of users are right-handed and they hold their phone with that hand, it's actually more comfortable to press the affirmation button when it's on the left, because the button is more likely to be within the user's thumb-arc. Buttons on the right-side of the screen require the user to pull their thumb inward into a less-comfortable position.

ContentDialog dans AppWindow ou Xaml IslandsContentDialog in AppWindow or Xaml Islands

REMARQUE : Cette section concerne les applications ciblant Windows 10, version 1903 ou versions ultérieures.NOTE: This section applies only to apps that target Windows 10, version 1903 or later. AppWindow et XAML Islands ne sont pas disponibles dans les versions antérieures.AppWindow and XAML Islands are not available in earlier versions. Pour plus d’informations sur les versions, voir Applications adaptatives de version.For more info about versioning, see Version adaptive apps.

Par défaut, le contenu de boîtes de dialogue s’affiche de manière modale, en fonction de la racine ApplicationView.By default, content dialogs display modally relative to the root ApplicationView. Lorsque vous utilisez ContentDialog dans AppWindow ou XAML Island, vous devez définir manuellement XamlRoot dans la boîte de dialogue à la racine de l’hôte XAML.When you use ContentDialog inside of either an AppWindow or a XAML Island, you need to manually set the XamlRoot on the dialog to the root of the XAML host.

Pour ce faire, définissez la propriété XamlRoot de ContentDialog sur le même XamlRoot en tant qu’élément déjà présent dans AppWindow ou XAML Islands, comme illustré ici.To do so, set the ContentDialog's XamlRoot property to the same XamlRoot as an element already in the AppWindow or XAML Island, as shown here.

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

Avertissement

Un seul ContentDialog peut être ouvert à la fois sur un même thread.There can only be one ContentDialog open per thread at a time. Toute tentative d’ouverture de deux ContentDialog lève une exception, même si la tentative d’ouverture se fait dans des AppWindows distinctes.Attempting to open two ContentDialogs will throw an exception, even if they are attempting to open in separate AppWindows.

Obtenir l’exemple de codeGet the sample code