Controles de cuadro de diálogoDialog controls

Los cuadros de diálogo son superposiciones modales en la interfaz de usuario que proporcionan información contextual sobre la aplicación.Dialog controls are modal UI overlays that provide contextual app information. Los cuadros de diálogo bloquean las interacciones con la ventana de la aplicación hasta que se descarten de forma explícita.They block interactions with the app window until being explicitly dismissed. A menudo solicitan algún tipo de acción por parte del usuario.They often request some kind of action from the user.

Ejemplo de un cuadro de diálogo

Obtención de la biblioteca de la interfaz de usuario de WindowsGet the Windows UI Library

Logotipo de WinUI

La biblioteca de interfaz de usuario de Windows 2.2 o posterior incluye una nueva plantilla para este control que usa esquinas redondeadas.Windows UI Library 2.2 or later includes a new template for this control that uses rounded corners. Para obtener más información, consulta Radio de redondeo.For more info, see Corner radius. WinUI es un paquete NuGet que contiene nuevas características de interfaz de usuario y controles para aplicaciones de Windows.WinUI is a NuGet package that contains new controls and UI features for Windows apps. Para obtener más información e instrucciones sobre la instalación, consulta el artículo Windows UI Library (Biblioteca de interfaz de usuario de Windows).For more info, including installation instructions, see Windows UI Library.

API de plataforma: Clase ContentDialogPlatform APIs: ContentDialog class

¿Es este el control adecuado?Is this the right control?

Use los cuadros de diálogo para notificar a los usuarios información importante o para solicitar información adicional o confirmación para completar una acción.Use dialogs to notify users of important information or to request confirmation or additional info before an action can be completed.

Para obtener recomendaciones sobre cuándo usar un control flotante frente a cuándo usar un cuadro de diálogo (un control similar), vea Cuadros de diálogo y controles flotantes.For recommendations on when to use a dialog vs. when to use a flyout (a similar control), see Dialogs and flyouts.

EjemplosExamples

XAML Controls GalleryXAML Controls Gallery
XAML controls gallery

Si tienes instalada la aplicación XAML Controls Gallery, haz clic aquí para abrirla y ver ContentDialog o Flyout en acción.If you have the XAML Controls Gallery app installed, click here to open the app and see the ContentDialog or Flyout in action.

Directrices generalesGeneral guidelines

  • Identifica claramente el problema o el objetivo del usuario en la primera línea del texto del cuadro de diálogo.Clearly identify the issue or the user's objective in the first line of the dialog's text.
  • El título del cuadro de diálogo es la instrucción principal y es opcional.The dialog title is the main instruction and is optional.
    • Usa un título corto para explicar lo que se necesita hacer con el cuadro de diálogo.Use a short title to explain what people need to do with the dialog.
    • Puedes omitir el título si vas a usar el cuadro de diálogo para transmitir un mensaje sencillo, un error o una pregunta.If you're using the dialog to deliver a simple message, error or question, you can optionally omit the title. Deja que el texto del contenido transmita esta información esencial.Rely on the content text to deliver that core information.
    • Asegúrate de que el título esté relacionado directamente con las opciones de botón.Make sure that the title relates directly to the button choices.
  • El contenido del cuadro de diálogo contiene el texto descriptivo y es obligatorio.The dialog content contains the descriptive text and is required.
    • Presenta el mensaje, el error o la pregunta de bloqueo de la manera más sencilla posible.Present the message, error, or blocking question as simply as possible.
    • Si se usa un cuadro de diálogo, usa el área de contenido para proporcionar más detalles o definir terminología.If a dialog title is used, use the content area to provide more detail or define terminology. No repitas el título con otras palabras ligeramente distintas.Don't repeat the title with slightly different wording.
  • Al menos debe aparecer un botón de cuadro de diálogo.At least one dialog button must appear.
    • Asegúrese de que el cuadro de diálogo tiene al menos un botón correspondiente a una acción segura y no destructiva como "Entendido", "Cerrar" o "Cancelar".Ensure that your dialog has at least one button corresponding to a safe, nondestructive action like "Got it!", "Close", or "Cancel". Use la API de CloseButton para agregar este botón.Use the CloseButton API to add this button.
    • Use respuestas específicas al contenido o a la instrucción principal como texto del botón.Use specific responses to the main instruction or content as button text. Un ejemplo sería: "¿Quieres permitir que nombreDeAplicación acceda a tu ubicación?", seguido de los botones "Permitir" y "Bloquear".An example is, "Do you want to allow AppName to access your location?", followed by "Allow" and "Block" buttons. Cuando las respuestas son específicas, se comprenden con mayor rapidez y la toma de decisiones resulta eficaz.Specific responses can be understood more quickly, resulting in efficient decision making.
    • Asegúrese de que el texto de los botones de acción sea conciso.Ensure that the text of the action buttons is concise. Las cadenas cortas permiten al usuario realizar una selección de manera rápida y segura.Short strings enable the user to make a choice quickly and confidently.
    • Además de la acción segura y no destructiva, opcionalmente podrá presentar al usuario uno o dos botones de acción relacionados con la instrucción principal.In addition to the safe, nondestructive action, you may optionally present the user with one or two action buttons related to the main instruction. Estos botones de acción "hacerlo" confirman el principal punto del cuadro de diálogo.These "do it" action buttons confirm the main point of the dialog. Use las API de PrimaryButton y SecondaryButton APIs para agregar estas acciones "hacerlo".Use the PrimaryButton and SecondaryButton APIs to add these "do it" actions.
    • Los botones de acción "hacerlo" deberían aparecer a la izquierda del resto.The "do it" action button(s) should appear as the leftmost buttons. La acción segura y no destructiva debe aparecer como el botón situado más a la derecha.The safe, nondestructive action should appear as the rightmost button.
    • Opcionalmente, puede elegir diferenciar uno de los tres botones como el botón predeterminado del cuadro de diálogo.You may optionally choose to differentiate one of the three buttons as the dialog's default button. Use la API de DefaultButton para diferenciar uno de los botones.Use the DefaultButton API to differentiate one of the buttons.
  • No uses cuadros de diálogo en el caso de los errores que son contextuales para un lugar específico de la página, como los errores de validación (en los campos de contraseña, por ejemplo); usa el lienzo de la aplicación para mostrar errores en línea.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.
  • Use la clase ContentDialog para compilar la experiencia de cuadro de diálogo.Use the ContentDialog class to build your dialog experience. No use la API de MessageDialog en desuso.Don't use the deprecated MessageDialog API.

Creación de un cuadro de diálogoHow to create a dialog

Para crear un cuadro de diálogo, usa la clase ContentDialog.To create a dialog, you use the ContentDialog class. Puedes crear un cuadro de diálogo en el código o el marcado.You can create a dialog in code or markup. Aunque suele ser más fácil definir los elementos de la interfaz de usuario en XAML, en el caso de un cuadro de diálogo simple, es más sencillo usar código solamente.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. En este ejemplo se crea un cuadro de diálogo para notificar al usuario que no hay conexión Wi-Fi y luego se usa el método ShowAsync para mostrarlo.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();
}

Cuando el usuario hace clic en un botón de cuadro de diálogo, el método ShowAsync devuelve una enumeración ContentDialogResult para que sepas en qué botón hace clic el usuario.When the user clicks a dialog button, the ShowAsync method returns a ContentDialogResult to let you know which button the user clicks.

El cuadro de diálogo de este ejemplo formula una pregunta y usa el valor devuelto ContentDialogResult para determinar la respuesta del usuario.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.
    }
}

Proporcione una acción de prueba de erroresProvide a safe action

Dado que los cuadros de diálogo bloquean la interacción del usuario, y que los botones son el mecanismo principal para que los usuarios descarten el cuadro de diálogo, asegúrese de que el diálogo contiene al menos un botón "seguro" y un botón no destructivo como "Cerrar" o "Entendido".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!". Todos los cuadros de diálogo deben contener al menos un botón de acción segura para cerrar el cuadro de diálogo.All dialogs should contain at least one safe action button to close the dialog. Esto garantiza que el usuario puede cerrar con confianza el cuadro de diálogo sin realizar una acción.This ensures that the user can confidently close the dialog without performing an action.
Un cuadro de diálogo con un botónAn 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();
}

Cuando los cuadros de diálogo se usan para mostrar una pregunta de bloqueo, su cuadro de diálogo debe presentar al usuario los botones de acción relacionados con la pregunta.When dialogs are used to display a blocking question, your dialog should present the user with action buttons related to the question. El botón "seguro" y no destructivo puede ir acompañado de uno o dos botones de acción "hacerlo".The "safe" and nondestructive button may be accompanied by one or two "do it" action buttons. Cuando se le presenten al usuario varias opciones, asegúrate de que los botones explican con claridad las acciones "hacerlo" y segura o "no hacerlo" relacionadas con la pregunta propuesta.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.

Un cuadro de diálogo con dos botones

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

Los cuadros de diálogo de tres botones se usan cuando le presentan al usuario dos acciones "hacerlo" y una acción "no hacerlo".Three button dialogs are used when you present the user with two "do it" actions and a "don't do it" action. Se deben usar cuadros de diálogo de tres botones con moderación con distinciones claras entre la acción secundaria y la acción seguro/cerrar.Three button dialogs should be used sparingly with clear distinctions between the secondary action and the safe/close action.

Cuadro de diálogo de tres botones

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

Los tres botones de cuadro de diálogoThe three dialog buttons

ContentDialog cuenta con tres tipos diferentes de botones que puede usar para compilar una experiencia de cuadro de diálogo.ContentDialog has three different types of buttons that you can use to build a dialog experience.

  • CloseButton (obligatorio): representa la acción no destructiva y segura que permite al usuario salir del cuadro de diálogo.CloseButton - Required - Represents the safe, nondestructive action that enables the user to exit the dialog. Aparece como el botón que se encuentra situado más a la derecha.Appears as the rightmost button.
  • PrimaryButton (opcional): representa la primera acción "hacerlo".PrimaryButton - Optional - Represents the first "do it" action. Aparece como el botón que se encuentra situado más a la izquierda.Appears as the leftmost button.
  • SecondaryButton (opcional): representa la segunda acción "hacerlo".SecondaryButton - Optional - Represents the second "do it" action. Aparece como el botón central.Appears as the middle button.

Con los botones integrados, los botones se colocarán correctamente; asegúrese de que responden correctamente a eventos de teclado, de que el área de comandos permanece visible incluso cuando el teclado en pantalla está activado y de que el aspecto del cuadro de diálogo es coherente con otros cuadros de diálogo.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

Cada cuadro de diálogo debe contener un botón de acción segura y no destructiva que permita al usuario salir del cuadro de diálogo con confianza.Every dialog should contain a safe, nondestructive action button that enables the user to confidently exit the dialog.

Use la API de ContentDialog.CloseButton para crear este botón.Use the ContentDialog.CloseButton API to create this button. Esto le permite crear la experiencia de usuario adecuada para todas las entradas como el mouse, el teclado, las funciones táctiles y el controlador para juegos.This allows you to create the right user experience for all inputs including mouse, keyboard, touch, and gamepad. Esta experiencia tendrá lugar cuando:This experience will happen when:

  1. El usuario haga clic o pulse en el CloseButtonThe user clicks or taps on the CloseButton
  2. El usuario presione el botón del sistema AtrásThe user presses the system back button
  3. El usuario presione la tecla ESC del tecladoThe user presses the ESC button on the keyboard
  4. El usuario presione el botón B del controlador para juegosThe user presses Gamepad B

Cuando el usuario hace clic en un botón de cuadro de diálogo, el método ShowAsync devuelve una enumeración ContentDialogResult para que sepas en qué botón hace clic el usuario.When the user clicks a dialog button, the ShowAsync method returns a ContentDialogResult to let you know which button the user clicks. Si se presiona en CloseButton se devuelve ContentDialogResult.None.Pressing on the CloseButton returns ContentDialogResult.None.

PrimaryButton y SecondaryButtonPrimaryButton and SecondaryButton

Además del CloseButton, opcionalmente puede presentar al usuario uno o dos botones de acción relacionados con la instrucción principal.In addition to the CloseButton, you may optionally present the user with one or two action buttons related to the main instruction. Aproveche el PrimaryButton para la primera acción "hacerlo" y el SecondaryButton para la segunda acción "hacerlo".Leverage PrimaryButton for the first "do it" action, and SecondaryButton for the second "do it" action. En los cuadros de diálogo de tres botones, el PrimaryButton suele representar la acción afirmativa "hacerlo", mientras que el SecondaryButton suele representar una acción "hacerlo" neutra o secundaria.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. Por ejemplo, una aplicación puede avisar al usuario que se suscriba a un servicio.For example, an app may prompt the user to subscribe to a service. El PrimaryButton como la acción "hacerlo" afirmativa hospedaría el texto Suscribirse mientras que el SecondaryButton como la acción "hacerlo" hospedaría el texto Pruébalo.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. El CloseButton permitiría al usuario cancelar sin llevar a cabo cualquiera de las acciones.The CloseButton would allow the user to cancel without performing either action.

Cuando el usuario hace clic en el PrimaryButton, el método ShowAsync devuelve ContentDialogResult.Primary.When the user clicks on the PrimaryButton, the ShowAsync method returns ContentDialogResult.Primary. Cuando el usuario hace clic en el SecondaryButton, el método ShowAsync devuelve ContentDialogResult.Secondary.When the user clicks on the SecondaryButton, the ShowAsync method returns ContentDialogResult.Secondary.

Cuadro de diálogo de tres botones

DefaultButtonDefaultButton

Opcionalmente, puede elegir diferenciar uno de los tres botones como el botón predeterminado.You may optionally choose to differentiate one of the three buttons as the default button. Especificar el botón predeterminado hace que se produzca lo siguiente:Specifying the default button causes the following to happen:

  • El botón recibe el tratamiento visual del botón de énfasisThe button receives the Accent Button visual treatment
  • El botón responderá a la tecla ENTRAR automáticamenteThe button will respond to the ENTER key automatically
    • Cuando el usuario presiona la tecla ENTRAR del teclado, se activará el controlador de clic asociado con el botón predeterminado y el ContentDialogResult devolverá el valor asociado con el botón predeterminadoWhen 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 el usuario ha situado el foco del teclado en un control que controla ENTRAR, el botón predeterminado no responderá al presionar ENTRARIf the user has placed Keyboard Focus on a control that handles ENTER, the Default Button will not respond to ENTER presses
  • El botón recibirá el foco automáticamente cuando se abra el cuadro de diálogo, a menos que el contenido del cuadro de diálogo contenga un elemento de interfaz de usuario activable.The button will receive focus automatically when the Dialog is opened unless the dialog's content contains focusable UI

Use la propiedad ContentDialog.DefaultButton para indicar el botón predeterminado.Use the ContentDialog.DefaultButton property to indicate the default button. De manera predeterminada, no se establece ningún botón predeterminado.By default, no default button is set.

Un cuadro de diálogo de tres botones con un botón predeterminado

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

Cuadros de diálogo de confirmación (Aceptar/Cancelar)Confirmation dialogs (OK/Cancel)

Un cuadro de diálogo de confirmación ofrece a los usuarios la posibilidad de confirmar que desean realizar una acción.A confirmation dialog gives users the chance to confirm that they want to perform an action. Pueden confirman la acción o cancelarla.They can affirm the action, or choose to cancel. Un cuadro de diálogo de confirmación típico tiene dos botones: un botón de afirmación ("Aceptar") y un botón de cancelación.A typical confirmation dialog has two buttons: an affirmation ("OK") button and a cancel button.

  • En general, el botón afirmación debe estar a la izquierda (el botón primario) y el botón de cancelación (el botón secundario) debe estar en la derecha.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
  • Como se explicó en la sección de recomendaciones generales, usa botones con texto que identifique respuestas específicas a la instrucción principal o al contenido.As noted in the general recommendations section, use buttons with text that identifies specific responses to the main instruction or content.

Algunas plataformas colocan el botón de afirmación a la derecha en lugar de a la izquierda.Some platforms put the affirmation button on the right instead of the left. Entonces, ¿por qué recomendamos colocarlo a la izquierda?So why do we recommend putting it on the left? Si supones que la mayoría de los usuarios son diestros y sujetan su teléfono con esa mano, realmente resulta más cómodo presionar el botón de afirmación cuando está a la izquierda, porque es más probable que el botón esté dentro del arco del pulgar del usuario. Los botones situados en el lado derecho de la pantalla requerirán que el usuario cambie la posición de su pulgar hacia dentro a una posición menos cómoda.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 en AppWindow o islas de XamlContentDialog in AppWindow or Xaml Islands

NOTA: Esta sección es aplicable a las aplicaciones diseñadas para Windows 10, versión 1903 o posterior.NOTE: This section applies only to apps that target Windows 10, version 1903 or later. Las Islas de XAML y AppWindow no están disponibles en versiones anteriores.AppWindow and XAML Islands are not available in earlier versions. Para obtener más información acerca de las versiones, consulte el aplicaciones de versión adaptable.For more info about versioning, see Version adaptive apps.

De manera predeterminada, los cuadros de diálogo muestran de forma modal con respecto a la raíz ApplicationView.By default, content dialogs display modally relative to the root ApplicationView. Cuando use ContentDialog dentro de cualquiera isla AppWindow o XAML, deberá establecer manualmente la XamlRoot en el cuadro de diálogo a la raíz del host 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.

Para ello, establezca la propiedad de XamlRoot del ContentDialog a la misma XamlRoot como un elemento que ya está en el AppWindow o isla de XAML, como se muestra aquí.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();
}

Advertencia

Solo puede haber uno ContentDialog abierto en cada subproceso a la vez.There can only be one ContentDialog open per thread at a time. Al intentar abrir dos ContentDialogs producirá una excepción, incluso si está intentando abrir en AppWindows independiente.Attempting to open two ContentDialogs will throw an exception, even if they are attempting to open in separate AppWindows.

Obtención del código de ejemploGet the sample code