Partilhar via

Menu deslizante da barra de comandos

  • Artigo

O submenu da barra de comandos permite que você forneça aos usuários acesso fácil a tarefas comuns, mostrando comandos em uma barra de ferramentas flutuante relacionada a um elemento na tela da interface do usuário.

Um submenu da barra de comandos de revisão de texto expandido

Como a CommandBar , o CommandBarFlyout tem propriedades de Comandos Primários e Comandos Secundários que pode usar para adicionar comandos. Você pode colocar comandos em uma das coleções, ou em ambas. Quando e como os comandos primário e secundário são exibidos depende do modo de exibição.

O desdobrável da barra de comandos tem dois modos de exibição: recolhido e expandido.

  • No modo recolhido, apenas os comandos primários são apresentados. Se a caixa de opções da barra de comandos contiver comandos primários e secundários, um botão "ver mais", representado por reticências [...], será exibido. Isso permite que o usuário tenha acesso aos comandos secundários fazendo a transição para o modo expandido.
  • No modo expandido, os comandos primário e secundário são mostrados. (Se o controle tiver apenas itens secundários, eles serão mostrados de forma semelhante ao controle MenuFlyout.)

Será este o controlo correto?

Use o controlo de sobrevoo da barra de comandos para mostrar uma coleção de comandos ao utilizador, como botões e itens de menu, no contexto de um elemento na interface da aplicação.

O menu suspenso da barra de comandos é o controle recomendado para criar menus de contexto. Isso permite que os comandos comuns (como Copiar, Recortar, Colar, Excluir, Compartilhar ou comandos de seleção de texto) que são contextualmente relevantes para o cenário do menu de contexto sejam adicionados como comandos primários para que sejam mostrados como uma única linha horizontal no submenu da barra de comandos. O TextCommandBarFlyout já está configurado adequadamente para exibir comandos de texto automaticamente nos controles TextBox, TextBlock, RichEditBox, RichTextBlock e PasswordBox. Um CommandBarFlyout pode ser usado para substituir os comandos de texto padrão em controles de texto.

Para mostrar comandos contextuais em itens de lista, siga as orientações em Comandos Contextuais para Coleções e Listas.

Invocação proativa versus reativa

Normalmente, existem duas maneiras de invocar uma janela de sobreposição ou menu associado a um elemento na sua tela de interface do utilizador: invocação proativa e invocação reativa.

Na chamada proativa, os comandos aparecem automaticamente quando o usuário interage com o item ao qual os comandos estão associados. Por exemplo, comandos de formatação de texto podem aparecer quando o usuário seleciona texto em uma caixa de texto. Nesse caso, o desdobrável da barra de comandos não ganha foco. Em vez disso, ele apresenta comandos relevantes próximos ao item com o qual o usuário está interagindo. Se o usuário não interagir com os comandos, eles serão descartados.

Na chamada reativa, os comandos são mostrados em resposta a uma ação explícita do usuário para solicitar os comandos; por exemplo, um clique com o botão direito do mouse. Isto corresponde ao conceito tradicional de um menu de contexto .

Você pode usar o CommandBarFlyout de qualquer maneira, ou até mesmo uma mistura dos dois.

Criar um submenu da barra de comandos

Abra o aplicativo WinUI 3 Gallery e veja o CommandBarFlyout em ação

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

Este exemplo mostra como criar um flyout da barra de comandos e usá-lo tanto de forma proativa quanto reativa. Quando a imagem é tocada, o submenu é mostrado em seu modo recolhido. Quando mostrado como um menu de contexto, o flyout é mostrado no seu modo expandido. Em ambos os casos, o usuário pode expandir ou recolher o submenu depois que ele é aberto.

<Grid>
    <Grid.Resources>
        <CommandBarFlyout x:Name="ImageCommandsFlyout">
            <AppBarButton Label="Favorite" Icon="OutlineStar" ToolTipService.ToolTip="Favorite"/>
            <AppBarButton Label="Copy" Icon="Copy" ToolTipService.ToolTip="Copy"/>
            <AppBarButton Label="Share" Icon="Share" ToolTipService.ToolTip="Share"/>
            <CommandBarFlyout.SecondaryCommands>
                <AppBarButton Label="Rotate" Icon="Rotate"/>
                <AppBarButton Label="Delete" Icon="Delete"/>
            </CommandBarFlyout.SecondaryCommands>
        </CommandBarFlyout>
    </Grid.Resources>

    <Image Source="Assets/image1.png" Width="300"
           Tapped="Image_Tapped" 
           FlyoutBase.AttachedFlyout="{x:Bind ImageCommandsFlyout}"
           ContextFlyout="{x:Bind ImageCommandsFlyout}"/>
</Grid>

private void Image_Tapped(object sender, TappedRoutedEventArgs e)
{
    var flyout = FlyoutBase.GetAttachedFlyout((FrameworkElement)sender);
    var options = new FlyoutShowOptions()
    {
        // Position shows the flyout next to the pointer.
        // "Transient" ShowMode makes the flyout open in its collapsed state.
        Position = e.GetPosition((FrameworkElement)sender),
        ShowMode = FlyoutShowMode.Transient
    };
    flyout?.ShowAt((FrameworkElement)sender, options);
}

Aqui está o painel flutuante da barra de comandos no seu estado recolhido.

Exemplo de um painel de comandos recolhido

Aqui está o mesmo submenu da barra de comandos em seu estado expandido mostrando comandos secundários.

Exemplo de um submenu da barra de comandos expandido

Mostrar comandos proativamente

Quando se mostram proativamente comandos contextuais, apenas os comandos primários devem ser exibidos por padrão (o desdobrável da barra de comandos deve estar fechado). Coloque os comandos mais importantes na coleção de comandos primários e os comandos adicionais que tradicionalmente iriam em um menu de contexto para a coleção de comandos secundários.

Para mostrar comandos proativamente, normalmente você manipula o evento Click ou Tapped para mostrar o flyout da barra de comandos. Defina o ShowMode do submenu como Transitório ou TransientWithDismissOnPointerMoveAway para abrir o submenu em seu modo recolhido sem tirar o foco.

Os controles de texto têm uma propriedade SelectionFlyout. Quando você atribui um submenu a essa propriedade, ele é mostrado automaticamente quando o texto é selecionado.

Mostrar comandos de forma reativa

Ao mostrar comandos contextuais reativamente, num menu de atalho, os comandos secundários são apresentados por padrão (o flyout da barra de comandos deverá ser expandido). Nesse caso, o submenu da barra de comandos pode ter comandos primários e secundários ou apenas comandos secundários.

Para mostrar comandos em um menu de contexto, normalmente você atribui o submenu à propriedade ContextFlyout de um elemento da interface do usuário. Dessa forma, a abertura do submenu é manipulada pelo elemento e você não precisa fazer mais nada.

Se você manipular a exibição do submenu por conta própria (por exemplo, em um evento RightTapped), defina o ShowMode do submenu como Standard para abrir o submenu em seu modo expandido e dar-lhe foco.

Dica

Para saber mais sobre as opções ao mostrar um submenu e como controlar o posicionamento do submenu, veja Submenus.

Mostrar sempre um CommandBarFlyout expandido

Quando você tem comandos primários e secundários em um CommandBarFlyout, o botão "ver mais" [...] é exibido por padrão e pode ser usado para expandir e recolher os comandos secundários. Se quiser manter seu CommandBarFlyout no modo expandido e mostrar os comandos secundários o tempo todo, você pode usar a propriedade CommandBarFlyout.AlwaysExpanded.

Quando a propriedade AlwaysExpanded é definida como true, o botão "ver mais" não é mostrado e o usuário não é capaz de alternar o estado expandido do controle. O CommandBarFlyout ainda será descartado como de costume quando um comando secundário for clicado ou o usuário clicar fora do flyout.

Essa propriedade só terá efeito se o CommandBarFlyout tiver comandos secundários. Se não houver comandos secundários, o CommandBarFlyout estará sempre no modo colapsado.

Dica

Você ainda pode recolher e expandir o CommandBarFlyout programaticamente ao ajustar a propriedade IsOpen, mesmo quando a propriedade AlwaysExpanded estiver definida como true.

Comandos e conteúdo

O controle CommandBarFlyout tem 2 propriedades que você pode usar para adicionar comandos e conteúdo: PrimaryCommands e SecondaryCommands.

Por padrão, os itens da barra de comandos são adicionados à coleção PrimaryCommands. Esses comandos são mostrados na barra de comandos e são visíveis nos modos recolhido e expandido. Ao contrário de CommandBar, os comandos primários não transbordam automaticamente para os comandos secundários e podem ser truncados.

Você também pode adicionar comandos à coleção SecondaryCommands. Os comandos secundários são mostrados na parte do menu do controle e são visíveis apenas no modo expandido.

Se houver comandos comuns (como Copiar, Recortar, Colar, Excluir, Compartilhar ou comandos de seleção de texto) que sejam importantes para o cenário, é recomendável adicioná-los como comandos primários em vez de comandos secundários.

Botões da barra de aplicações

Você pode preencher os PrimaryCommands e SecondaryCommands diretamente com os controlos AppBarButton , AppBarToggleButton e AppBarSeparator .

Os controles de botão da barra de aplicativos são caracterizados por um ícone e rótulo de texto. Esses controlos são otimizados para uso numa barra de comandos e a sua aparência altera-se dependendo de se o controlo está na barra de comandos ou no menu de transbordo.

  • No Windows App SDK 1.5 e posterior: botões da barra de aplicativos usados como comandos principais são mostrados na barra de comandos com o rótulo de texto e o ícone (se ambos estiverem definidos). 
    <AppBarButton Icon="Copy" Label="Copy"/>
  • No Windows App SDK 1.4 e versões anteriores: botões da barra de aplicativos usados como comandos principais são mostrados na barra de comandos apenas com seu ícone; O rótulo de texto não é mostrado. Recomendamos que você use uma dica de ferramenta para mostrar uma descrição de texto do comando, conforme mostrado aqui. 
    <AppBarButton Icon="Copy" ToolTipService.ToolTip="Copy"/>
  • Os botões da barra de aplicativos usados como comandos secundários são mostrados no menu, com o rótulo e o ícone visíveis.

Ícones

Considere fornecer ícones de itens de menu para:

  • Os itens mais usados.
  • Itens de menu cujo ícone é padrão ou bem conhecido.
  • Itens de menu cujo ícone ilustra bem o que o comando faz.

Não se sinta obrigado a fornecer ícones para comandos que não têm uma visualização padrão. Ícones enigmáticos não são úteis, criam confusão visual e impedem que os usuários se concentrem nos itens importantes do menu.

Outros conteúdos

Você pode adicionar outros controlos a um flyout da barra de comandos, envolvendo-os num AppBarElementContainer. Isso permite que você adicione controles como DropDownButton ou SplitButton, ou adicione contêineres como StackPanel para criar uma interface do usuário mais complexa.

Para ser adicionado à coleção de comandos primária ou secundária de um submenu da barra de comandos, um elemento deve implementar a interface ICommandBarElement. AppBarElementContainer é um wrapper que implementa essa interface para que você possa adicionar um elemento a uma barra de comandos, mesmo que ela não implemente a interface em si.

Aqui, é utilizado um AppBarElementContainer para adicionar elementos extra a um menu expansível da barra de comandos. Um SplitButton é adicionado aos comandos principais para habilitar o alinhamento do texto. Um StackPanel é adicionado aos comandos secundários para permitir um layout mais complexo para controles de zoom.

Dica

Por padrão, os elementos projetados para a tela do aplicativo podem não parecer corretos em uma barra de comandos. Quando você adiciona um elemento usando AppBarElementContainer, há algumas etapas que você deve seguir para fazer com que o elemento corresponda a outros elementos da barra de comandos:

  • Substitua os pincéis padrão por de estilo leve para fazer com que o plano de fundo e a borda do elemento correspondam aos botões da barra de aplicativos.
  • Ajuste o tamanho e a posição do elemento.
  • Envolva ícones em uma Viewbox com uma largura e altura de 16px.

Observação

Este exemplo mostra apenas a interface do usuário do menu expansível da barra de comandos, sem implementar nenhum dos comandos exibidos. Para saber mais sobre como implementar os comandos, consulte Botões e Conceitos básicos de design de comandos.

<CommandBarFlyout>
    <AppBarButton Icon="Cut" Label="Cut" ToolTipService.ToolTip="Cut"/>
    <AppBarButton Icon="Copy" Label="Copy" ToolTipService.ToolTip="Copy"/>
    <AppBarButton Icon="Paste" Label="Paste" ToolTipService.ToolTip="Paste"/>
    <!-- Alignment controls -->
    <AppBarElementContainer>
         <SplitButton ToolTipService.ToolTip="Alignment">
            <SplitButton.Resources>
                <!-- Override default brushes to make the SplitButton 
                     match other command bar elements. -->
                <Style TargetType="SplitButton">
                    <Setter Property="Height" Value="38"/>
                </Style>
                <SolidColorBrush x:Key="SplitButtonBackground"
                                 Color="Transparent"/>
                <SolidColorBrush x:Key="SplitButtonBackgroundPressed"
                                 Color="{ThemeResource SystemListMediumColor}"/>
                <SolidColorBrush x:Key="SplitButtonBackgroundPointerOver"
                                 Color="{ThemeResource SystemListLowColor}"/>
                <SolidColorBrush x:Key="SplitButtonBorderBrush" Color="Transparent"/>
                <SolidColorBrush x:Key="SplitButtonBorderBrushPointerOver"
                                 Color="Transparent"/>
                <SolidColorBrush x:Key="SplitButtonBorderBrushChecked"
                                 Color="Transparent"/>
            </SplitButton.Resources>
            <SplitButton.Content>
                <Viewbox Width="16" Height="16" Margin="0,2,0,0">
                    <SymbolIcon Symbol="AlignLeft"/>
                </Viewbox>
            </SplitButton.Content>
            <SplitButton.Flyout>
                <MenuFlyout>
                    <MenuFlyoutItem Icon="AlignLeft" Text="Align left"/>
                    <MenuFlyoutItem Icon="AlignCenter" Text="Center"/>
                    <MenuFlyoutItem Icon="AlignRight" Text="Align right"/>
                </MenuFlyout>
            </SplitButton.Flyout>
        </SplitButton>
    </AppBarElementContainer>
    <!-- end Alignment controls -->
    <CommandBarFlyout.SecondaryCommands>
        <!-- Zoom controls -->
        <AppBarElementContainer>
            <AppBarElementContainer.Resources>
                <!-- Override default brushes to make the Buttons
                     match other command bar elements. -->
                <SolidColorBrush x:Key="ButtonBackground"
                                 Color="Transparent"/>
                <SolidColorBrush x:Key="ButtonBackgroundPressed"
                                 Color="{ThemeResource SystemListMediumColor}"/>
                <SolidColorBrush x:Key="ButtonBackgroundPointerOver"
                                 Color="{ThemeResource SystemListLowColor}"/>
                <SolidColorBrush x:Key="ButtonBorderBrush"
                                 Color="Transparent"/>
                <SolidColorBrush x:Key="ButtonBorderBrushPointerOver"
                                 Color="Transparent"/>
                <SolidColorBrush x:Key="ButtonBorderBrushChecked"
                                 Color="Transparent"/>
                <Style TargetType="TextBlock">
                    <Setter Property="VerticalAlignment" Value="Center"/>
                </Style>
                <Style TargetType="Button">
                    <Setter Property="Height" Value="40"/>
                    <Setter Property="Width" Value="40"/>
                </Style>
            </AppBarElementContainer.Resources>
            <Grid Margin="12,-4">
                <Grid.ColumnDefinitions>
                    <ColumnDefinition Width="Auto"/>
                    <ColumnDefinition Width="76"/>
                    <ColumnDefinition Width="Auto"/>
                </Grid.ColumnDefinitions>
                <Viewbox Width="16" Height="16" Margin="0,2,0,0">
                    <SymbolIcon Symbol="Zoom"/>
                </Viewbox>
                <TextBlock Text="Zoom" Margin="10,0,0,0" Grid.Column="1"/>
                <StackPanel Orientation="Horizontal" Grid.Column="2">
                    <Button ToolTipService.ToolTip="Zoom out">
                        <Viewbox Width="16" Height="16">
                            <SymbolIcon Symbol="ZoomOut"/>
                        </Viewbox>
                    </Button>
                    <TextBlock Text="50%" Width="40"
                               HorizontalTextAlignment="Center"/>
                    <Button ToolTipService.ToolTip="Zoom in">
                        <Viewbox Width="16" Height="16">
                            <SymbolIcon Symbol="ZoomIn"/>
                        </Viewbox>
                    </Button>
                </StackPanel>
            </Grid>
        </AppBarElementContainer>
        <!-- end Zoom controls -->
        <AppBarSeparator/>
        <AppBarButton Label="Undo" Icon="Undo"/>
        <AppBarButton Label="Redo" Icon="Redo"/>
        <AppBarButton Label="Select all" Icon="SelectAll"/>
    </CommandBarFlyout.SecondaryCommands>
</CommandBarFlyout>

Aqui está o submenu recolhido da barra de comandos com um botão dividido (SplitButton) aberto.

Um submenu da barra de comandos com um botão de divisão

Aqui está o desdobramento da barra de comandos expandida com uma interface de zoom personalizada no menu.

Um flyout de barra de comandos com interface de utilizador complexa

Criar um menu de contexto apenas com comandos secundários

Você pode usar um flyout da barra de comandos com apenas comandos secundários para criar um menu de contexto que tenha a mesma aparência e comportamento do flyout de menu.

<Grid>
    <Grid.Resources>
        <!-- A command bar flyout with only secondary commands. -->
        <CommandBarFlyout x:Name="ContextMenu">
            <CommandBarFlyout.SecondaryCommands>
                <AppBarButton Label="Copy" Icon="Copy"/>
                <AppBarButton Label="Save" Icon="Save"/>
                <AppBarButton Label="Print" Icon="Print"/>
                <AppBarSeparator />
                <AppBarButton Label="Properties"/>
            </CommandBarFlyout.SecondaryCommands>
        </CommandBarFlyout>
    </Grid.Resources>

    <Image Source="Assets/image1.png" Width="300"
           ContextFlyout="{x:Bind ContextMenu}"/>
</Grid>

Aqui está o submenu da barra de comandos como um menu de contexto.

Um submenu da barra de comandos com apenas comandos secundários

Você também pode usar um CommandBarFlyout com um DropDownButton para criar um menu padrão.

<CommandBarFlyout>
    <AppBarButton Icon="Placeholder"/>
    <AppBarElementContainer>
        <DropDownButton Content="Mail">
            <DropDownButton.Resources>
                <!-- Override default brushes to make the DropDownButton
                     match other command bar elements. -->
                <Style TargetType="DropDownButton">
                    <Setter Property="Height" Value="38"/>
                </Style>
                <SolidColorBrush x:Key="ButtonBackground"
                                 Color="Transparent"/>
                <SolidColorBrush x:Key="ButtonBackgroundPressed"
                                 Color="{ThemeResource SystemListMediumColor}"/>
                <SolidColorBrush x:Key="ButtonBackgroundPointerOver"
                                 Color="{ThemeResource SystemListLowColor}"/>

                <SolidColorBrush x:Key="ButtonBorderBrush"
                                 Color="Transparent"/>
                <SolidColorBrush x:Key="ButtonBorderBrushPointerOver"
                                 Color="Transparent"/>
                <SolidColorBrush x:Key="ButtonBorderBrushChecked"
                                 Color="Transparent"/>
            </DropDownButton.Resources>
            <DropDownButton.Flyout>
                <CommandBarFlyout Placement="BottomEdgeAlignedLeft">
                    <CommandBarFlyout.SecondaryCommands>
                        <AppBarButton Icon="MailReply" Label="Reply"/>
                        <AppBarButton Icon="MailReplyAll" Label="Reply all"/>
                        <AppBarButton Icon="MailForward" Label="Forward"/>
                    </CommandBarFlyout.SecondaryCommands>
                </CommandBarFlyout>
            </DropDownButton.Flyout>
        </DropDownButton>
    </AppBarElementContainer>
    <AppBarButton Icon="Placeholder"/>
    <AppBarButton Icon="Placeholder"/>
</CommandBarFlyout>

Aqui está um menu de botão suspenso em um submenu da barra de comandos.

Um submenu da barra de comandos com menu de botão suspenso

Submenus da barra de comandos para controles de texto

O TextCommandBarFlyout é um flyout especializado da barra de comandos que contém comandos para editar texto. Cada controle de texto mostra o TextCommandBarFlyout automaticamente como um menu de contexto (clique com o botão direito do mouse) ou quando o texto é selecionado. A janela desdobrável da barra de comandos de texto adapta-se à seleção de texto para mostrar apenas comandos relevantes.

Aqui está um submenu da barra de comandos de texto na seleção de texto.

Um submenu da barra de comandos de texto recolhido

Aqui está uma barra de comandos de texto expandida que mostra os comandos secundários.

Um submenu da barra de comandos de texto expandido

Comandos disponíveis

Esta tabela mostra os comandos incluídos em um TextCommandBarFlyout e quando eles são mostrados.

Comando Mostrado...
Negrito quando o controle de texto não é somente leitura (somente RichEditBox).
Itálico quando o controlo de texto não é de leitura apenas (aplicável apenas ao RichEditBox).
Sublinhar quando o controle de texto não é somente leitura (somente RichEditBox).
Verificação quando IsSpellCheckEnabled é true e texto com erros ortográficos é selecionado.
Cortar se o controlo de texto não for de leitura apenas e o texto estiver selecionado.
Copiar quando o texto é selecionado.
Colar quando o controle de texto não está configurado como só de leitura e a área de transferência tem conteúdo.
Desfazer quando há uma ação que pode ser desfeita.
Selecionar tudo quando o texto pode ser selecionado.

Barra de comandos de texto com submenus personalizados

TextCommandBarFlyout não pode ser personalizado e é gerenciado automaticamente por cada controle de texto. No entanto, você pode substituir o padrão TextCommandBarFlyout por comandos personalizados.

  • Para substituir o TextCommandBarFlyout padrão mostrado na seleção de texto, pode criar um CommandBarFlyout personalizado (ou outro tipo de elemento de sobreposição) e atribuí-lo à propriedade SelectionFlyout. Se definir SelectionFlyout como nulo , não serão mostrados comandos na seleção.
  • Para substituir o TextCommandBarFlyout padrão mostrado como o menu de contexto, atribua um CommandBarFlyout personalizado (ou outro tipo de submenu) à propriedade ContextFlyout num controlo de texto. Se definires ContextFlyout como nulo , o menu apresentado em versões anteriores do controlo de texto será mostrado em vez do TextCommandBarFlyout.

Dispensa leve

Controles de descarte leve, como menus, menus de contexto e outros painéis suspensos, mantêm o foco do teclado e do gamepad dentro da interface de utilizador transitória até serem descartados. Para fornecer uma pista visual para esse comportamento, os controles de descarte de luz no Xbox desenharão uma sobreposição que diminui a visibilidade da interface do usuário fora do escopo. Esse comportamento pode ser modificado com a propriedade LightDismissOverlayMode. Por padrão, as interfaces de usuário transitórias desenham a sobreposição de descarte leve no Xbox (Auto), mas não em outras famílias de dispositivos. Você pode optar por forçar a sobreposição a estar sempre On ou sempre Off.

<CommandBarFlyout LightDismissOverlayMode="Off" /> >

UWP e WinUI 2

Importante

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

Esta seção contém informações que você precisa para usar o controle em um aplicativo UWP ou WinUI 2.

O controle CommandBarFlyout para aplicativos UWP está incluído como parte do WinUI 2. Para obter mais informações, incluindo instruções de instalação, consulte WinUI 2. As APIs para esse controle existem nos namespaces Windows.UI.Xaml.Controls (UWP) e Microsoft.UI.Xaml.Controls (WinUI).

Recomendamos usar o WinUI 2 mais recente para obter os estilos e modelos mais atuais para todos os controlos. WinUI 2.2 ou posterior inclui um novo modelo para este controle que usa cantos arredondados. Para obter mais informações, consulte Raio de canto.

Para usar o código neste artigo com WinUI 2, use um alias em XAML (usamos muxc) para representar as APIs da Biblioteca da Interface do Usuário do Windows incluídas em seu projeto. Consulte Introdução ao WinUI 2 para obter mais informações.

xmlns:muxc="using:Microsoft.UI.Xaml.Controls"

<muxc:CommandBarFlyout />