Barra de comandos

As barras de comandos proporcionam aos usuários um acesso fácil às tarefas mais comuns do seu aplicativo. As barras de comandos podem oferecer um acesso aos comandos no nível do aplicativo ou específicos da página e podem ser usadas com qualquer padrão de navegação.

Esse é o controle correto?

O controle CommandBar é um controle de uso geral, flexível e leve que pode exibir conteúdo complexo, como imagens ou blocos de texto, bem como comandos simples, como controles AppBarButton, AppBarToggleButton e AppBarSeparator .

Observação

O XAML fornece os controles AppBar e CommandBar. Você deve usar o AppBar somente quando estiver atualizando um aplicativo Universal do Windows 8 que usa o AppBar e precisar minimizar as alterações. Para novos aplicativos no Windows 10, recomendamos usar o controle CommandBar. Este documento pressupõe que você esteja usando o controle CommandBar.

Anatomia

Por padrão, a barra de comandos mostra uma linha de botões de ícone e um botão opcional "ver mais", que é representado por reticências [...]. Aqui está a barra de comandos criada pelo código de exemplo mostrado posteriormente. Ele é mostrado em seu estado compacto fechado.

A barra de comandos também pode ser mostrada em um estado mínimo fechado semelhante a este. Consulte a seção Estados abertos e fechados para obter mais informações.

Aqui está a mesma barra de comandos em seu estado aberto. Os rótulos identificam as partes principais do controle.

A barra de comandos é dividida em 4 áreas principais:

• A área de conteúdo é alinhada ao lado esquerdo da barra. Ela será mostrada se a propriedade Content estiver preenchida.
• A área de comandos primários está alinhada à direita da barra. Ela será mostrada se a propriedade PrimaryCommands estiver preenchida.
• O botão "ver mais" [...] é mostrado à direita da barra. Pressionar o botão "ver mais" [...] revela rótulos de comandos primários e abre o menu flutuante se houver comandos secundários. O botão não ficará visível quando não houver rótulos de comandos primários ou secundários. Para alterar o comportamento padrão, use a propriedade OverflowButtonVisibility.
• O menu Estouro de capacidade é mostrado somente quando a barra de comandos é aberta e a propriedade SecondaryCommands é preenchida. Quando o espaço é limitado, os comandos primários se movem para a área SecondaryCommands. Para alterar esse comportamento padrão, use a propriedade IsDynamicOverflowEnabled.

O layout é invertido quando o FlowDirection é RightToLeft.

Posicionamento

As barras de comandos podem ser colocadas na parte superior da janela do aplicativo, na parte inferior da janela do aplicativo e embutidas, inserindo-as em um controle de layout como Grid.row.

• Para dispositivos portáteis pequenos, recomendamos posicionar barras de comando na parte inferior da tela para facilitar o acesso.
• Para dispositivos com telas maiores, colocar as barras de comandos próximas do topo da janela as torna mais perceptíveis e detectáveis.

Use a API DiagonalSizeInInches para determinar o tamanho da tela física.

As barras de comandos podem ser colocadas nas seguintes regiões de tela em telas de exibição única (exemplo à esquerda) e em telas de exibição múltipla (exemplo à direita). As barras de comando embutidas podem ser colocadas em qualquer lugar no espaço de ação.

Dispositivos de toque: se a barra de comandos precisar permanecer visível para um usuário quando o teclado virtual ou o SIP (Painel de Entrada Virtual) aparecer, você poderá atribuir a barra de comandos à propriedade BottomAppBar de uma página e ela será movida para permanecer visível quando o SIP estiver presente. Caso contrário, você deve colocar a barra de comandos embutida e posicionada em relação ao conteúdo do aplicativo.

UWP e WinUI 2

Importante

As informações e exemplos neste artigo são otimizados para aplicativos que usam o SDK do Aplicativo Windows e o WinUI 3, mas geralmente são aplicáveis a aplicativos UWP que usam o WinUI 2. Consulte a referência de API da UWP para obter informações e exemplos específicos da plataforma.

Esta seção contém informações necessárias para usar o controle em um aplicativo UWP ou WinUI 2.

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

• APIs UWP: classe CommandBar, classe AppBarButton, classe AppBarToggleButton, classe AppBarSeparator
• Abra o aplicativo Galeria do WinUI 2 e veja o CommandBar em ação. Os aplicativos da Galeria do WinUI 2 incluem exemplos interativos da maioria dos controles, recursos e funcionalidades do WinUI 2. Obtenha o aplicativo na Microsoft Store ou o código-fonte no GitHub.

É recomendável 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 esse controle que usa cantos arredondados. Para obter mais informações, confira Raio de canto.

O estilo automático de um SplitButton em um CommandBar requer que você use o controle SplitButton do WinUI 2.6 ou posterior.

Criar uma barra de comandos

• APIs importantes: classe CommandBar, classe AppBarButton, classe AppBarToggleButton, classe AppBarSeparator

Abra o aplicativo Galeria do WinUI 3 e veja o CommandBar em ação.

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

Este exemplo cria a barra de comandos mostrada anteriormente.

<CommandBar>
    <AppBarToggleButton Icon="Shuffle" Label="Shuffle" Click="AppBarButton_Click" />
    <AppBarToggleButton Icon="RepeatAll" Label="Repeat" Click="AppBarButton_Click"/>
    <AppBarSeparator/>
    <AppBarButton Icon="Back" Label="Back" Click="AppBarButton_Click"/>
    <AppBarButton Icon="Stop" Label="Stop" Click="AppBarButton_Click"/>
    <AppBarButton Icon="Play" Label="Play" Click="AppBarButton_Click"/>
    <AppBarButton Icon="Forward" Label="Forward" Click="AppBarButton_Click"/>

    <CommandBar.SecondaryCommands>
        <AppBarButton Label="Like" Click="AppBarButton_Click"/>
        <AppBarButton Label="Dislike" Click="AppBarButton_Click"/>
    </CommandBar.SecondaryCommands>

    <CommandBar.Content>
        <TextBlock Text="Now playing..." Margin="12,14"/>
    </CommandBar.Content>
</CommandBar>

Comandos e conteúdo

O controle CommandBar tem 3 propriedades que você pode usar para adicionar comandos e conteúdo: PrimaryCommands, SecondaryCommands e Content.

Comandos

Por padrão, os itens da barra de comandos são adicionados à coleção PrimaryCommands. Você deve adicionar os comandos em sua ordem de importância para que aqueles mais importantes fiquem sempre visíveis. Quando a largura de barra de comandos é alterada, como quando os usuários redimensionam a janela do aplicativo, os comandos primários se movem dinamicamente entre a barra de comandos e o menu Estouro de capacidade nos pontos de interrupção. Para alterar esse comportamento padrão, use a propriedade IsDynamicOverflowEnabled.

Nas telas menores (largura de 320 epx), caberão, no máximo, quatro comandos primários na barra de comandos.

Você também pode adicionar comandos à coleção SecondaryCommands, exibidos no menu Estouro de capacidade.

Você pode mover comandos programaticamente entre os PrimaryCommands e SecondaryCommands, conforme necessário.

• Se houver um comando que deva aparecer de forma consistente em várias páginas, é melhor mantê-lo em um local consistente.
• Recomendamos colocar os comandos Aceitar, Sim e OK à esquerda de Rejeitar, Não e Cancelar. A consistência oferece aos usuários a confiança para se movimentarem no sistema e os ajuda a transferir o conhecimento que possuem sobre a navegação de aplicativos de um produto para outro.

Botões da barra do aplicativo

Os PrimaryCommands e os SecondaryCommands podem ser preenchidos somente com tipos que implementam a interface ICommandBarElement, que inclui os elementos de comando AppBarButton, AppBarToggleButton e AppBarSeparator.

Se você quiser incluir um tipo diferente de elemento em seus PrimaryCommands ou SecondaryCommands, poderá usar a classe AppBarElementContainer . Isso servirá como um wrapper para o elemento e permitirá que o elemento seja exibido em um CommandBar.

Os controles de botão da barra de aplicativos são caracterizados por um ícone e um rótulo de texto. Esses controles são otimizados para uso em uma barra de comandos, e sua aparência muda se o controle é usado na barra de comandos ou no menu Estouro de capacidade.

Ícones

O tamanho dos ícones, quando mostrados na área de comando principal, é 20 x 20 px. No menu de estouro, os ícones são exibidos em 16 x 16 px. Se você usar SymbolIcon, FontIcon ou PathIcon, o ícone será escalado automaticamente para o tamanho correto, sem perda de fidelidade, quando o comando entrar na área de comando secundário.

Para obter mais informações e exemplos de como definir o ícone, confira a documentação da classe AppBarButton.

Rótulos

A propriedade IsCompact de AppBarButton determina se o rótulo é exibido. Em um controle CommandBar, a barra de comandos substitui automaticamente a propriedade IsCompact do botão, conforme a barra de comandos é aberta ou fechada.

Para posicionar os rótulos do botão da barra do aplicativo, use a propriedade DefaultLabelPosition da CommandBar.

<CommandBar DefaultLabelPosition="Right">
    <AppBarToggleButton Icon="Edit" Label="Edit"/>
    <AppBarToggleButton Icon="Share" Label="Share"/>
</CommandBar>

Em janelas maiores, considere mover os rótulos para a direita dos ícones de botões da barra do aplicativo para melhorar a legibilidade. Os rótulos na parte inferior exigem que os usuários abram a barra de comandos para revelar os rótulos, enquanto os rótulos à direita ficam visíveis mesmo quando a barra de comandos está fechada.

Nos menus Estouro de capacidade, os rótulos são posicionados à direita dos ícones por padrão, e LabelPosition é ignorado. Você pode ajustar o estilo definindo a propriedade CommandBarOverflowPresenterStyle como um estilo cujo destino seja CommandBarOverflowPresenter.

Os rótulos de botões devem ser curtos, preferencialmente uma única palavra. Rótulos mais longos, posicionados abaixo de um ícone, serão ajustados em várias linhas, aumentando assim a altura geral da barra de comandos aberta. Você pode incluir um caractere de hífen flexível (0x00AD) no texto para um rótulo para sugerir o limite de caractere em que uma quebra de palavra deve ocorrer. Em XAML, você expressa isso usando uma sequência de escape, como esta:

<AppBarButton Icon="Back" Label="Areally&#x00AD;longlabel"/>

Quando o rótulo é quebrado no local sugerido, ele se parece com isso.

SplitButton

Você pode exibir um SplitButton em um CommandBar usando a classe interna SplitButtonCommandBarStyle e AppBarElementContainer. SplitButtonCommandBarStyle fornece visuais para que um SplitButton se pareça com um AppBarButton, enquanto AppBarElementContainer é uma classe wrapper que fornece a funcionalidade que SplitButton precisa para agir como um AppBarButton.

Quando você encapsula um SplitButton em um AppBarElementContainer e o coloca em um CommandBar, o SplitButtonCommandBarStyle recurso é aplicado automaticamente.

Este código de exemplo cria e exibe um SplitButton dentro de um CommandBar:

<CommandBar>
    <AppBarButton Icon="Copy" ToolTipService.ToolTip="Copy" Label="Copy"/>
    <AppBarElementContainer>
        <muxc:SplitButton ToolTipService.ToolTip="Insert" Content="Insert">
            <muxc:SplitButton.Flyout>
                <MenuFlyout Placement="RightEdgeAlignedTop">
                    <MenuFlyoutItem Text="Insert above"/>
                    <MenuFlyoutItem Text="Insert between"/>
                    <MenuFlyoutItem  Text="Insert below"/>
                </MenuFlyout>
            </muxc:SplitButton.Flyout>
        </muxc:SplitButton>
    </AppBarElementContainer>
    <AppBarButton Label="Select all"/>
    <AppBarButton Label="Delete" Icon="Delete"/>
</CommandBar>

Menus e submenus

Considere agrupamentos lógicos para os comandos, como colocar Responder, Responder a Todos e Encaminhar em um menu Responder. Em geral, embora um botão da barra do aplicativo ative um único comando, ele também pode ser usado para mostrar um MenuFlyout ou Flyout com conteúdo personalizado.

Outro conteúdo

Você pode adicionar qualquer elemento XAML à área de conteúdo definindo a propriedade Content . Se você quiser adicionar mais de um elemento, será necessário colocá-los em um contêiner de painel e tornar o painel o único filho da propriedade Content.

Quando o estouro dinâmico estiver habilitado, o conteúdo não será recortado porque os comandos primários podem ser movidos para o menu Estouro de capacidade. Caso contrário, os comandos primários têm preferência e poderão fazer com que o conteúdo seja recortado.

Quando ClosedDisplayMode é Compact, o conteúdo poderá ser recortado se for maior do que o tamanho compacto da barra de comandos. Você deverá tratar os eventos Opening e Closed para mostrar ou ocultar partes da interface do usuário na área de conteúdo para que eles não sejam recortados. Consulte a seção Estados abertos e fechados para obter mais informações.

Estados abertos e fechados

A barra de comandos pode ser aberta ou fechada. Quando estiver aberta, ela mostrará os botões de comandos primários com rótulos de texto e abrirá o menu Estouro de capacidade (se não houver comandos secundários). A barra de comandos abrirá o menu Estouro de capacidade para cima (acima dos comandos primários) ou para baixo (abaixo dos comandos primários). A direção padrão está ativa, mas se não houver espaço suficiente para abrir o menu Estouro de capacidade para cima, a barra de comandos irá abri-lo para baixo.

Um usuário pode alternar entre esses estados pressionando o botão "ver mais" [...]. Você pode alternar entre eles programaticamente definindo a propriedade IsOpen.

Você pode usar os eventos Opening, Opened, Closing e Closed para responder à barra de comandos que está sendo aberta ou fechada.

• Os eventos de abertura e fechamento ocorrem antes do início da animação de transição.
• Os eventos Aberto e Fechado ocorrem após a conclusão da transição.

Neste exemplo, os eventos Opening e Closing são usados para alterar a opacidade da barra de comandos. Quando a barra de comandos é fechada, ela é semitransparente para que o plano de fundo do aplicativo apareça. Quando a barra de comandos é aberta, a barra de comandos fica opaca para que o usuário possa se concentrar nos comandos.

<CommandBar Opening="CommandBar_Opening"
            Closing="CommandBar_Closing">
    <AppBarButton Icon="Accept" Label="Accept"/>
    <AppBarButton Icon="Edit" Label="Edit"/>
    <AppBarButton Icon="Save" Label="Save"/>
    <AppBarButton Icon="Cancel" Label="Cancel"/>
</CommandBar>

private void CommandBar_Opening(object sender, object e)
{
    CommandBar cb = sender as CommandBar;
    if (cb != null) cb.Background.Opacity = 1.0;
}

private void CommandBar_Closing(object sender, object e)
{
    CommandBar cb = sender as CommandBar;
    if (cb != null) cb.Background.Opacity = 0.5;
}

Épegajoso

Se um usuário interagir com outras partes de um aplicativo quando a barra de comandos estiver aberta, ela será fechada automaticamente. Esse recurso é chamado de light dismiss. Você pode controlar o comportamento de light dismiss ao definir a propriedade IsSticky. Quando IsSticky="true", a barra permanece aberta até que o usuário pressione o botão "ver mais" [...] ou selecione um item no menu flutuante.

Recomendamos evitar barras de comandos fixas porque elas não estão em conformidade com as expectativas dos usuários em relação aos comportamentos de light dismiss e de foco do teclado.

Modo de Exibição

Você pode controlar como a barra de comandos é mostrada em seu estado “fechada” definindo a propriedade ClosedDisplayMode. Existem 3 modos de exibição fechados para escolher:

• Compacto: o modo padrão. Mostra o conteúdo, os ícones de comando primários sem rótulos e o botão "ver mais" [...].
• Mínimo: Mostra apenas uma barra fina que funciona como o botão "ver mais" [...]. O usuário pode pressionar em qualquer lugar da barra para abri-la.
• Oculto: a barra de comandos não é mostrada quando é fechada. Isso pode ser útil para mostrar comandos contextuais com uma barra de comandos embutida. Nesse caso, você deve abrir a barra de comandos programaticamente definindo a propriedade IsOpen ou alterando o ClosedDisplayMode para Minimal ou Compact.

Aqui, uma barra de comandos é usada para conter comandos de formatação simples para um RichEditBox. Quando a caixa de edição não tem foco, os comandos de formatação podem distrair, portanto, ficam ocultos. Quando a caixa de edição está sendo usada, o ClosedDisplayMode da barra de comandos é alterado para Compact para que os comandos de formatação fiquem visíveis.

<StackPanel Width="300"
            GotFocus="EditStackPanel_GotFocus"
            LostFocus="EditStackPanel_LostFocus">
    <CommandBar x:Name="FormattingCommandBar" ClosedDisplayMode="Hidden">
        <AppBarButton Icon="Bold" Label="Bold" ToolTipService.ToolTip="Bold"/>
        <AppBarButton Icon="Italic" Label="Italic" ToolTipService.ToolTip="Italic"/>
        <AppBarButton Icon="Underline" Label="Underline" ToolTipService.ToolTip="Underline"/>
    </CommandBar>
    <RichEditBox Height="200"/>
</StackPanel>

private void EditStackPanel_GotFocus(object sender, RoutedEventArgs e)
{
    FormattingCommandBar.ClosedDisplayMode = AppBarClosedDisplayMode.Compact;
}

private void EditStackPanel_LostFocus(object sender, RoutedEventArgs e)
{
    FormattingCommandBar.ClosedDisplayMode = AppBarClosedDisplayMode.Hidden;
}

Observação

A implementação dos comandos de edição está além do escopo deste exemplo. Para obter mais informações, consulte o artigo RichEditBox .

Embora os modos Minimal e Hidden sejam úteis em algumas situações, lembre-se de que ocultar todas as ações pode confundir os usuários.

Alterar o ClosedDisplayMode para fornecer mais ou menos uma dica ao usuário afeta o layout dos elementos circundantes. Por outro lado, quando o CommandBar faz a transição entre fechado e aberto, isso não afeta o layout de outros elementos.

Obter o código de exemplo

• Exemplo de Galeria da WinUI: veja todos os controles XAML em um formato interativo.
• Exemplo de execução de comandos XAML

Artigos relacionados

• Noções básicas de design de comando para aplicativos do Windows
• Submenu da barra de comandos
• Submenu de menu e barra de menus
• Classe MenuFlyout
• Classe CommandBar