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 finalidade geral, flexível e leve que pode exibir conteúdo complexo, como imagens ou blocos de texto, e comandos simples, como os controles AppBarButton, AppBarToggleButton e AppBarSeparator.
Observação
O XAML fornece os controles AppBar e CommandBar. Use AppBar somente quando você estiver atualizando um aplicativo Universal do Windows 8 que usa AppBar e precisar minimizar as alterações. Para novos aplicativos no Windows 10, recomendamos usar o controle CommandBar. Este documento pressupõe que você está 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 [...]. Esta é a barra de comandos criada pelo código de exemplo mostrado posteriormente. Ela é mostrada em seu estado fechado e compacto.
A barra de comandos também pode ser mostrada em um estado fechado e minimizado com a seguinte aparência. Consulte a seção Estados abertos e fechados para obter mais informações.
Esta é a mesma barra de comandos em seu estado aberto. Os rótulos identificam as principais partes do controle.
A barra de comandos é dividida em 4 áreas principais:
- A área de conteúdo está alinhada à esquerda 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 comando primários e abre o menu de estouro 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 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 o posicionamento das barras de comandos na parte inferior da tela para fácil acessibilidade.
- 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 posicionadas nas seguintes regiões da tela, em telas de exibição única (exemplo à esquerda) e em telas com várias exibições (exemplo à direita). As barras de comandos embutidas podem ser colocadas em qualquer lugar no espaço de ação.
Dispositivos de toque: caso seja necessário que a barra de comandos fique visível para o usuário quando o teclado virtual ou o painel de entrada virtual (SIP) for exibido, 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 da 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 .
- UWP APIs: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. O 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
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 três 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 programaticamente comandos entre 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 dá aos usuários a confiança para se movimentar no sistema e ajuda-os a transferir seu conhecimento da navegação no aplicativo de um produto para outro.
Botões da barra de aplicativos
PrimaryCommands e SecondaryCommands só podem ser preenchidos 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 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 do aplicativo 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 rótulos, enquanto os rótulos à direita ficam visíveis mesmo quando a barra de comandos é 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 condicional (0x00AD) no texto de um rótulo para indicar o limite do caractere onde uma quebra de palavra deve ocorrer. Em XAML, isso é expresso usando-se uma sequência de escape, como esta:
<AppBarButton Icon="Back" Label="Areally­longlabel"/>
Quando o rótulo quebra automaticamente no local indicado, ele tem esta aparência.
SplitButton
Você pode exibir um SplitButton em um CommandBar usando a classe interna SplitButtonCommandBarStyle e AppBarElementContainer . SplitButtonCommandBarStyle fornece visuais para um SplitButton parecer 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 dos comandos como, por exemplo, 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.
Outros tipos de conteúdo
Você pode adicionar qualquer elemento XAML à área de conteúdo definindo a propriedade Content. Se quiser adicionar mais de um elemento, você precisa 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 estar aberta ou fechada. Quando estiver aberto, ele mostrará botões de comando primários com rótulos de texto e abrirá o menu de estouro (se 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 Opening e Closing ocorrem antes de começar a animação de transição.
- Os eventos Opened e Closed 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 está fechada, ela é semitransparente para que o plano de fundo do aplicativo apareça. Quando a barra de comandos está aberta, ela se torna 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;
}
IsSticky
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 permanecerá aberta até que o usuário pressione o botão "ver mais" [...] ou selecione um item no menu de estouro.
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. Há 3 modos de exibição fechada à sua escolha:
- Compacto: O modo padrão. Mostra conteúdo, ícones de comando primário sem rótulos e o botão "ver mais" [...].
- Mínimo: mostra apenas uma barra fina que atua como o botão "ver mais" [...]. O usuário pode pressionar em qualquer lugar na barra para abri-lo.
- Oculto: a barra de comandos não é mostrada quando é fechada. Isso pode ser útil para mostrar os comandos contextuais com uma barra de comandos embutida. Nesse caso, você deve abrir a barra de comandos programaticamente definindo a propriedade IsOpen ou alterando ClosedDisplayMode para Minimal ou Compact.
Aqui, uma barra de comandos é usada para manter os comandos de formatação simples para um RichEditBox. Quando a caixa de edição não tiver foco, os comandos de formatação podem distrair o usuário, por isso eles ficam ocultos. Quando a caixa de edição está sendo usada, ClosedDisplayMode da barra de comando é 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, tenha em mente que os usuários poderão ficar confusos se todas as ações foram ocultadas.
A alteração de ClosedDisplayMode para fornecer mais ou menos dicas para o usuário afeta o layout dos elementos ao redor. Em contraste, quando CommandBar faz a transição entre fechada e aberta, ela não afeta o layout dos outros elementos.
Obter o código de exemplo
- Exemplo da Galeria do WinUI – consulte todos os controles XAML em um formato interativo.
- Exemplo de execução de comandos XAML
Artigos relacionados
Windows developer
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de