Controles de diálogo

Os controles de caixa de diálogo são sobreposições modais da interface do usuário que fornecem informações contextuais do aplicativo. Eles bloqueiam as interações com a janela da aplicação até serem explicitamente descartados. Eles geralmente solicitam algum tipo de ação do usuário.

Será este o controlo correto?

Use caixas de diálogo para notificar os usuários sobre informações importantes ou para solicitar confirmação ou informações adicionais antes que uma ação possa ser concluída.

Para obter recomendações sobre quando usar uma caixa de diálogo ou quando usar um painel de deslocamento (um controlo semelhante), consulte Caixas de diálogo e painéis de deslocamento.

Orientações gerais

• Identifique claramente o problema ou o objetivo do usuário na primeira linha do texto da caixa de diálogo.
• O título da caixa de diálogo é a instrução principal e é opcional.
  • Use um título curto para explicar o que as pessoas precisam fazer com o diálogo.
  • Se estiver a utilizar a caixa de diálogo para enviar uma simples mensagem, erro ou pergunta, pode opcionalmente omitir o título. Confie no texto do conteúdo para fornecer essas informações principais.
  • Certifique-se de que o título se relaciona diretamente com as opções de botão.
• O conteúdo da caixa de diálogo contém o texto descritivo e é obrigatório.
  • Apresente a mensagem, erro ou pergunta de bloqueio da forma mais simples possível.
  • Se um título de caixa de diálogo for usado, use a área de conteúdo para fornecer mais detalhes ou definir terminologia. Não repita o título com palavras ligeiramente diferentes.
• Pelo menos um botão de diálogo deve aparecer.
  • Certifique-se de que sua caixa de diálogo tenha pelo menos um botão correspondente a uma ação segura e não destrutiva, como "Conseguiu!", "Fechar" ou "Cancelar". Use a API CloseButton para adicionar esse botão.
  • Use respostas específicas para a instrução principal ou conteúdo como texto de botão. Um exemplo é "Você deseja permitir que o AppName acesse sua localização?", seguido pelos botões "Permitir" e "Bloquear". As respostas específicas podem ser compreendidas mais rapidamente, resultando em uma tomada de decisão eficiente.
  • Certifique-se de que o texto dos botões de ação é conciso. Strings curtas permitem que o usuário faça uma escolha rápida e confiante.
  • Além da ação segura e não destrutiva, você pode, opcionalmente, apresentar ao usuário um ou dois botões de ação relacionados à instrução principal. Estes botões de ação "executar" confirmam o objetivo principal da caixa de diálogo. Utilize as APIs PrimaryButton e SecondaryButton para adicionar essas ações de "fazer isso".
  • O(s) botão(ões) de ação "do it" deve(m) aparecer como os botões mais à esquerda. A ação segura e não destrutiva deve aparecer como o botão mais à direita.
  • Opcionalmente, você pode optar por diferenciar um dos três botões como o botão padrão da caixa de diálogo. Use a API DefaultButton para diferenciar um dos botões.
• Não use caixas de diálogo para erros que são contextuais a um local específico da página, como erros de validação (em campos de senha, por exemplo), usando a área própria do aplicativo para mostrar erros em linha.
• Use a classe ContentDialog para criar sua experiência de diálogo. Não use a API MessageDialog preterida.

Criar uma caixa de diálogo

O aplicativo WinUI 3 Gallery inclui exemplos interativos da maioria dos controles, recursos e funcionalidades do WinUI 3. Obtenha o aplicativo no da Microsoft Store ou obtenha o código-fonte em do GitHub

Para criar uma caixa de diálogo, use a classe ContentDialog. Você pode criar uma caixa de diálogo em código ou marcação. Embora geralmente seja mais fácil definir elementos da interface do usuário em XAML, no caso de uma caixa de diálogo simples, pode ser mais fácil usar apenas código. Este exemplo cria uma caixa de diálogo para notificar o usuário de que não há conexão WiFi e, em seguida, usa o método ShowAsync para exibi-la.

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

Se a caixa de diálogo de conteúdo for mais complexa, pode ser mais fácil criá-la com XAML. Você pode criá-lo no arquivo XAML para a sua página ou pode criar uma subclasse de ContentDialog com o seu próprio arquivo .xaml e arquivo de código subjacente. Para obter exemplos completos de ambos, consulte a referência de classe [ContentDialog].

Não há nenhum modelo de item no Visual Studio para criar um novo arquivo de diálogo de conteúdo, mas você pode usar o modelo Página em Branco e modificar os arquivos resultantes para criar uma caixa de diálogo.

Para criar uma nova caixa de diálogo de conteúdo com XAML e code-behind

1. No painel Gerenciador de Soluções , clique com o botão direito do mouse no nome do projeto e selecione Adicionar > Novo Item...
2. Na caixa de diálogo Adicionar Novo Item , selecione WinUI na lista de modelos no lado esquerdo da janela.
3. Selecione o modelo Página em branco .
4. Dê o nome ao ficheiro. (Neste exemplo, o arquivo é chamado XamlContentDialog).
5. Pressione Adicionar.

No novo arquivo .xaml, altere as tags Page de abertura e fechamento para ContentDialog.

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

</Page>
-->

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

</ContentDialog>

No arquivo .xaml.cs, faça sua classe herdar de ContentDialog em vez de Page.

// public sealed partial class XamlContentDialog : Page

public sealed partial class XamlContentDialog : ContentDialog

Mostrar a caixa de diálogo

Para mostrar uma caixa de diálogo, chame o método ShowAsync .

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

Definir o XamlRoot

Ao mostrar um ContentDialog, deve definir manualmente a XamlRoot do diálogo como a raiz do host XAML. Para fazer isso, defina a propriedade XamlRoot do ContentDialog para ser o mesmo XamlRoot que um elemento que já está na árvore XAML.

Se o ContentDialog for mostrado a partir de uma Page, você poderá definir a propriedade XamlRoot do ContentDialog como XamlRoot da Page, conforme mostrado no exemplo anterior.

Window não tem uma propriedade XamlRoot, portanto, se a caixa de diálogo for mostrada de uma Window, defina a propriedade XamlRoot da caixa de diálogo como a do elemento de conteúdo raiz da Window, conforme mostrado aqui.

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

Responder aos botões de diálogo

Quando o utilizador clica num botão de diálogo, o método ShowAsync retorna um ContentDialogResult para indicar em que botão o utilizador clicou.

Esta caixa de diálogo de exemplo faz uma pergunta e utiliza o resultado de diálogo retornado ContentDialogResult para determinar a resposta do utilizador.

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 uma ação segura

Como as caixas de diálogo bloqueiam a interação do usuário e como os botões são o principal mecanismo para os usuários descartarem a caixa de diálogo, certifique-se de que a caixa de diálogo contenha pelo menos um botão "seguro" e não destrutivo, como "Fechar" ou "Conseguiu!". Todas as caixas de diálogo devem conter pelo menos um botão de ação segura para fechar a caixa de diálogo. Isso garante que o usuário possa fechar a caixa de diálogo com confiança sem executar uma ação.

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

Quando as caixas de diálogo são usadas para exibir uma pergunta de bloqueio, sua caixa de diálogo deve apresentar ao usuário botões de ação relacionados à pergunta. O botão "seguro" e não destrutivo pode ser acompanhado por um ou dois botões de ação "do it". Ao apresentar ao usuário várias opções, certifique-se de que os botões expliquem claramente as ações "do it" e safe/"don't do it" relacionadas à pergunta proposta.

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

Caixas de diálogo de três botões são usadas quando se apresenta ao utilizador duas ações que realiza e uma ação que não realiza. As caixas de diálogo de três botões devem ser usadas com moderação, com distinções claras entre a ação secundária e a ação segura/fechar.

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

Os três botões de diálogo

ContentDialog tem três tipos diferentes de botões que você pode usar para criar uma experiência de diálogo.

• CloseButton - Obrigatório - Representa a ação segura e não destrutiva que permite ao usuário sair da caixa de diálogo. Aparece como o botão mais à direita.
• PrimaryButton - é opcional - Representa a primeira ação "fazer". Aparece como o botão mais à esquerda.
• SecondaryButton - Opcional - Representa a segunda ação "executar". Aparece como o botão do meio.

O uso dos botões internos posicionará os botões adequadamente, garantirá que eles respondam corretamente aos eventos do teclado, garantirá que a área de comando permaneça visível mesmo quando o teclado na tela estiver ativo e fará com que a caixa de diálogo pareça consistente com outras caixas de diálogo.

FecharBotão

Cada caixa de diálogo deve conter um botão de ação seguro e não destrutivo que permita ao usuário sair da caixa de diálogo com confiança.

Use a API ContentDialog.CloseButton para criar esse botão. Isso permite que você crie a experiência de usuário certa para todas as entradas, incluindo mouse, teclado, toque e gamepad. Esta experiência acontecerá quando:

• O usuário clica ou toca no CloseButton.
• O usuário pressiona o botão Voltar do sistema.
• O usuário pressiona o botão ESC no teclado.
• O usuário pressiona o Gamepad B.

Quando o utilizador clica num botão de diálogo, o método ShowAsync retorna um ContentDialogResult para indicar em que botão o utilizador clicou. Pressionar o botão CloseButton retorna ContentDialogResult.None.

Botão Primário e Botão Secundário

Além do CloseButton, você pode, opcionalmente, apresentar ao usuário um ou dois botões de ação relacionados à instrução principal. Aproveite PrimaryButton para a primeira ação "do it" e SecondaryButton para a segunda ação "do it". Em diálogos de três botões, o Botão Primário geralmente representa a ação afirmativa de "executar", enquanto o Botão Secundário geralmente representa uma ação "executar" neutra ou secundária. Por exemplo, um aplicativo pode solicitar que o usuário assine um serviço. O PrimaryButton como a ação afirmativa "do it" hospedaria o texto Subscribe, enquanto o SecondaryButton como a ação neutra "do it" hospedaria o texto Try it. O CloseButton permitiria que o usuário cancelasse sem executar nenhuma das ações.

Quando o usuário clica no PrimaryButton, o método ShowAsync retorna ContentDialogResult.Primary. Quando o usuário clica no SecondaryButton, o método ShowAsync retorna ContentDialogResult.Secondary.

BotãoPadrão

Opcionalmente, você pode optar por diferenciar um dos três botões como o botão padrão. Especificar o botão padrão faz com que aconteça o seguinte:

• O botão recebe o tratamento visual de botão de destaque.
• O botão responderá automaticamente à tecla ENTER
  • Quando o usuário pressiona a tecla ENTER no teclado, o manipulador de clique associado ao botão padrão será acionado e o ContentDialogResult retornará o valor associado ao botão padrão
  • Se o usuário tiver colocado o foco do teclado em um controle que manipula ENTER, o botão padrão não responderá às pressionações ENTER
• O botão receberá foco automaticamente quando a caixa de diálogo for aberta, a menos que o conteúdo da caixa de diálogo contenha elementos de interface que possam ser focalizados.

Use a propriedade ContentDialog.DefaultButton para indicar o botão padrão. Por padrão, nenhum botão padrão é definido.

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

Caixas de diálogo de confirmação (OK/Cancelar)

Uma caixa de diálogo de confirmação dá aos usuários a chance de confirmar que desejam executar uma ação. Eles podem confirmar a ação, ou optar por cancelar. Uma caixa de diálogo de confirmação típica tem dois botões: um botão de afirmação ("OK") e um botão de cancelamento.

• Em geral, o botão de afirmação deve estar à esquerda (o botão primário) e o botão cancelar (o botão secundário) deve estar à direita.

  
• Conforme observado na seção de recomendações gerais, use botões com texto que identifique respostas específicas para a instrução ou conteúdo principal.

UWP e WinUI 2

As APIs para esse controle existem no namespace Windows.UI.Xaml.Controls .

Recomendamos usar a WinUI 2 mais recente para obter os estilos e modelos mais atuais para todos os controles. WinUI 2.2 ou posterior inclui um novo modelo para este controle que usa cantos arredondados. Consulte Raio de cantopara obter mais informações.

ContentDialog em AppWindow ou Ilhas Xaml

NOTA: Esta secção aplica-se apenas a aplicações destinadas ao Windows 10, versão 1903 ou posterior. AppWindow e Ilhas XAML não estão disponíveis em versões anteriores. Para saber mais sobre controle de versão, consulte Aplicações adaptativas à versão.

Por padrão, as caixas de diálogo de conteúdo são exibidas de forma modal em relação à raiz ApplicationView. Quando se utiliza um ContentDialog dentro de um AppWindow ou de uma Ilha XAML, é necessário definir manualmente o XamlRoot na caixa de diálogo para a raiz do host XAML.

Para fazer isso, defina a propriedade XamlRoot do ContentDialog para o mesmo XamlRoot que um elemento já presente na AppWindow ou na ilha XAML, conforme mostrado aqui.

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

Artigos relacionados

• Dicas de ferramentas
• Menus e menu de contexto
• da classe Flyout
• classe ContentDialog