Barra de título

O controle TitleBar fornece uma maneira simplificada de criar uma barra de título personalizada para seu aplicativo. A barra de título é um componente fundamental de uma interface do usuário de um aplicativo Windows que identifica o aplicativo por meio de seu ícone e título, abriga os botões de legenda do sistema que permitem que um usuário feche, maximize, minimize e restaure a janela e permite que um usuário arraste a janela ao redor da tela.

Você pode usar uma barra de título personalizada para integrar melhor a área da barra de título à interface do usuário do aplicativo. A barra de título pode ser personalizada para corresponder ao estilo visual do aplicativo usando o tema Mica. Ele pode incluir outras informações relevantes, como um título de documento ou o estado atual (por exemplo, "Edição", "Exibição", etc.). Ele também pode hospedar outros controles WinUI 3, como AutoSuggestBox e PersonPicture, fornecendo uma experiência coesa do usuário para seu aplicativo.

Captura de tela de uma janela do aplicativo com uma barra de título personalizada

Esse é o controle correto?

Use o controle TitleBar quando quiser integrar a área da barra de título à interface do usuário do aplicativo usando personalizações como subtítulos, temas Mica e integrações com controles WinUI.

Anatomia

Por padrão, a barra de título mostra apenas os botões de legenda do sistema. Outras partes da barra de título são mostradas ou ocultas dependendo das configurações de propriedade associadas.

A barra de título é dividida nessas áreas:

Captura de tela mostrando as partes de um controle de barra de título.

Botão Voltar:IsBackButtonEnabled, IsBackButtonVisible, BackRequested – um botão voltar interno para navegação.
Botão para alternar a visibilidade do painel:IsPaneToggleButtonVisible, PaneToggleRequested – este botão deve ser usado em conjunto com o controle NavigationView.
Left header:LeftHeader
Icon:IconSource
Title:Título
Subtítulo:Subtítulo
Content:Content
Right header:RightHeader
Região de arrastar mínima: Essa área é reservada ao lado dos botões de legenda do sistema para que o usuário sempre tenha um local para pegar a janela para arrastar.
Botões de legenda do sistema: Esses botões não fazem parte do controle TitleBar - ele simplesmente aloca espaço onde os botões de legenda aparecem, dependendo das configurações RTL ou LTR. Botões de legenda e personalizações são tratados pelo AppWindowTitleBar.

O layout é invertido quando o FlowDirection é RightToLeft.

Criar uma barra de título

ApIs importantes:classe TitleBar, propriedade Title

Abra o aplicativo da Galeria do WinUI 3 e veja a Barra de Títulos em ação

O aplicativo Da Galeria do WinUI 3 inclui exemplos interativos de controles e recursos do WinUI. Obtenha o aplicativo na Microsoft Store ou navegue pelo código-fonte em GitHub.

Este exemplo cria uma barra de título simples que substitui a barra de título do sistema. Ele tem um título, ícone e tema Mica.

<Window
    ...  >
    <Window.SystemBackdrop>
        <MicaBackdrop Kind="Base"/>
    </Window.SystemBackdrop>

    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition Height="Auto" />
            <RowDefinition Height="*" />
        </Grid.RowDefinitions>

        <TitleBar x:Name="SimpleTitleBar"
                  Title="My App">
            <TitleBar.IconSource>
                <FontIconSource Glyph="&#xF4AA;"/>
            </TitleBar.IconSource>
        </TitleBar>

        <!-- App content -->
        <Frame x:Name="RootFrame" Grid.Row="1"/>
    </Grid>
</Window>

public MainWindow()
{
    this.InitializeComponent();

    // Hides the default system title bar.
    ExtendsContentIntoTitleBar = true;
    // Replace system title bar with the WinUI TitleBar control. 
    SetTitleBar(SimpleTitleBar); 
}

Integração com NavigationView

O modo de exibição de Navegação inclui um botão embutido para voltar e um botão de alternância do painel. As diretrizes do Fluent Design recomendam que esses controles sejam colocados na barra de título quando uma barra de título personalizada é usada.

Este exemplo demonstra como integrar o controle da Barra de Título com o controle de NavigationView, ocultando o botão de voltar e o botão de alternância do painel na vista de navegação e usando os botões correspondentes na barra de título.

<Grid>
    <Grid.RowDefinitions>
        <RowDefinition Height="Auto" />
        <RowDefinition Height="*" />
    </Grid.RowDefinitions>

    <TitleBar Title="My App"
              IsBackButtonVisible="True"
              IsBackButtonEnabled="{x:Bind RootFrame.CanGoBack, Mode=OneWay}"
              BackRequested="TitleBar_BackRequested"
              IsPaneToggleButtonVisible="True"
              PaneToggleRequested="TitleBar_PaneToggleRequested">
    </TitleBar>

    <NavigationView x:Name="RootNavigationView" Grid.Row="1"
                    IsBackButtonVisible="Collapsed"
                    IsPaneToggleButtonVisible="False">
        <Frame x:Name="RootFrame" />
    </NavigationView>
</Grid>

private void TitleBar_BackRequested(TitleBar sender, object args)
{
    if (RootFrame.CanGoBack)
    {
        RootFrame.GoBack();
    }
}

private void TitleBar_PaneToggleRequested(TitleBar sender, object args)
{
    RootNavigationView.IsPaneOpen = !RootNavigationView.IsPaneOpen;
}

Personalizar regiões de arrasto

Os usuários movem uma janela arrastando sua barra de título. O controle TitleBar determina quais partes de sua área Content os usuários podem arrastar e quais partes recebem entrada de ponteiro, como cliques.

A partir do SDK do Aplicativo Windows 2.1.3, o controle TitleBar examina os elementos em seu conteúdo e exclui apenas controles interativos, como botões, caixas de texto e caixas de combinação, da região de arrastar. Espaços vazios e elementos não interativos, como um TextBlock, são arrastáveis por padrão, portanto, você não precisa alterar sua marcação. Em versões anteriores, o espaço vazio na área de conteúdo poderia bloquear o arrasto da janela. Esse comportamento padrão é a mudança de compatibilidade de tempo de execução do TitleBar_ContentDragRegions. Para obter mais informações, consulte RuntimeCompatibilityOptions.DisabledChanges.

APIs importantes:propriedade anexada TitleBar.IsDragRegion, propriedade AutoRefreshDragRegions, método RecomputeDragRegions

O exemplo a seguir baseia-se no exemplo da Galeria do WinUI 3. O conteúdo da barra de título é um Grid que contém uma AutoSuggestBox e um Button. Ambos os controles são clicáveis e o espaço vazio ao lado deles é arrastável.

<TitleBar x:Name="AppTitleBar" Title="My App">
    <TitleBar.Resources>
        <!-- Stretch the content across the available width of the title bar. -->
        <HorizontalAlignment x:Key="TitleBarContentHorizontalAlignment">Stretch</HorizontalAlignment>
    </TitleBar.Resources>
    <TitleBar.Content>
        <Grid ColumnSpacing="8">
            <Grid.ColumnDefinitions>
                <ColumnDefinition Width="*" />
                <ColumnDefinition Width="Auto" />
            </Grid.ColumnDefinitions>

            <AutoSuggestBox MaxWidth="580"
                            VerticalAlignment="Center"
                            PlaceholderText="Search..."
                            QueryIcon="Find" />

            <StackPanel x:Name="RightPanel"
                        Grid.Column="1"
                        Orientation="Horizontal"
                        Spacing="8"
                        VerticalAlignment="Center">
                <Button x:Name="StatusButton"
                        Content="Status"
                        Click="StatusButton_Click" />
            </StackPanel>
        </Grid>
    </TitleBar.Content>
</TitleBar>

Sobrescrever o comportamento de arrastar de um elemento

Para substituir o comportamento padrão de um elemento no conteúdo da barra de título, defina a propriedade anexada TitleBar.IsDragRegion . A propriedade é um valor booleano anulável.

Value	Behavior
Não definido (`null`)	O controle TitleBar decide. Controles interativos são clicáveis e outros elementos são arrastáveis.
`True`	O elemento é arrastável, mesmo que seja um controle interativo. A entrada de ponteiro no elemento move a janela, portanto os usuários não podem clicar no elemento.
`False`	O elemento é clicável, mesmo que não seja um controle interativo.

Você pode definir a propriedade em um painel, como um StackPanel:

Se você defini-lo como False, toda a área do painel será clicável, incluindo o espaço entre seus elementos filhos.
Se você defini-lo como True, o painel e seus elementos filhos são arrastáveis, exceto para os elementos filhos em que você define a propriedade como False.

Defina a propriedade no menor elemento que precisa dele, para que você não torne uma grande área da barra de título arrastável ou clicável por acidente.

Este exemplo torna um grupo de controles de formatação clicável como um todo, para que os usuários não arrastem a janela quando pressionarem o espaço entre os controles.

<StackPanel Orientation="Horizontal" Spacing="8" TitleBar.IsDragRegion="False">
    <ComboBox PlaceholderText="Font" />
    <ComboBox PlaceholderText="Size" />
    <ToggleButton Content="Bold" />
</StackPanel>

No código, chame SetIsDragRegion para definir o valor e chame ClearValue com IsDragRegionProperty para retornar ao comportamento padrão. Para ler o valor, chame GetIsDragRegion. Ele retornará null se a propriedade não estiver definida. Quando o valor é alterado, o controle TitleBar atualiza suas regiões de arrastar.

// Make the button draggable. Users can't click it.
TitleBar.SetIsDragRegion(StatusButton, true);

// Make the button clickable.
TitleBar.SetIsDragRegion(StatusButton, false);

// Clear the value so that the TitleBar control decides.
StatusButton.ClearValue(TitleBar.IsDragRegionProperty);

Atualizar regiões de arrastar quando o conteúdo for alterado

O controle TitleBar atualiza suas regiões de arrastar quando você define ou substitui seu conteúdo, quando o conteúdo é carregado, quando a barra de título altera o tamanho e quando o valor de TitleBar.IsDragRegion muda em um elemento.

Se você adicionar, remover ou redimensionar elementos no conteúdo da barra de título em tempo de execução, chame RecomputeDragRegions depois de fazer a alteração.

private void AddButton_Click(object sender, RoutedEventArgs e)
{
    RightPanel.Children.Insert(0, new Button { Content = "Extra" });

    // Update the drag regions so that the new button is clickable.
    AppTitleBar.RecomputeDragRegions();
}

Se o conteúdo da barra de título for alterado com frequência, você poderá definir AutoRefreshDragRegions para True em vez disso. Em seguida, o controle TitleBar atualiza suas regiões de arrastar após cada passe de layout. Essa opção pode afetar o desempenho, portanto, é False por padrão.

<TitleBar x:Name="AppTitleBar" Title="My App" AutoRefreshDragRegions="True">
    <!-- Title bar content that changes at run time. -->
</TitleBar>

Note

As regiões de arrastar afetam apenas a entrada do ponteiro. Eles não alteram o foco do teclado ou como Automação da Interface do Usuário clientes, como leitores de tela, interagem com os elementos na barra de título. Verifique se os controles interativos na barra de título ainda podem ser acessados com o teclado.

Se o aplicativo não usar o controle TitleBar, use a classe InputNonClientPointerSource para definir as regiões interativas da barra de título personalizada. Para obter mais informações, consulte conteúdo interativo.

Comentários

Esta página foi útil?

Última atualização em 2026-10-15