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 da interface de utilizador de uma aplicação Windows que identifica a aplicação através do seu ícone e título, contém os botões de legenda do sistema que permitem ao utilizador fechar, maximizar, minimizar e restaurar a janela, e permite ao utilizador arrastar a janela pelo ecrã.

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. Pode incluir outras informações relevantes, como o título de um documento ou o estado atual (por exemplo, "Edição", "Visualização", etc.). Também pode alojar outros controlos do WinUI 3, como o AutoSuggestBox e o PersonPicture, proporcionando uma experiência de utilizador coesa para a sua aplicação.

Captura de ecrã de uma janela da aplicação com uma barra de título personalizada

Será este o controlo correto?

Use o controle TitleBar quando quiser integrar a área da barra de título com a interface do usuário do aplicativo usando personalizações como legendas, 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 ocultadas, dependendo das configurações de propriedade associadas.

A barra de título está dividida nas seguintes á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 integrado para navegação.
Botão de alternância do painel:IsPaneToggleButtonVisible, PaneToggleRequested - Este botão destina-se a ser usado em conjunto com o controle NavigationView.
Cabeçalho esquerdo:CabeçalhoEsquerdo
Ícone:IconSource
Título:Título
Legenda:Legenda
Conteúdo:Conteúdo
Cabeçalho direito:RightHeader
Região de arrasto mínimo: Esta área é reservada ao lado dos botões de legenda do sistema para que o usuário sempre tenha um lugar 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. Os botões de legenda e as personalizações são manipulados pela AppWindowTitleBar.

O layout é invertido quando o FlowDirection está configurado para RightToLeft.

Criar uma barra de título

APIs importantes:classe TitleBar, propriedade Title

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

A aplicação WinUI 3 Gallery inclui exemplos interativos de controlos e funcionalidades WinUI. Descarrega a aplicação na Microsoft Store ou navega pelo código-fonte no GitHub.

Este exemplo cria uma barra de título simples que substitui a barra de título do sistema. 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

A vista Navegação tem um botão Voltar incorporado e um botão para alternar o painel. As diretrizes do Fluent Design recomendam que esses controles sejam colocados na barra de título quando uma barra de título personalizada for usada.

Este exemplo demonstra como integrar o controle TitleBar com um controle NavigationView ocultando o botão Voltar e o botão de alternância do painel no modo de exibição 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 áreas de arrasto

Os utilizadores movem uma janela arrastando a barra de título. O controlo TitleBar determina quais as partes da sua área de Conteúdo que os utilizadores podem arrastar e quais recebem entrada do ponteiro, como cliques.

A partir do SDK de Aplicações Windows 2.1.3, o controlo TitleBar examina os elementos do seu conteúdo e exclui apenas os controlos interativos, como botões, caixas de texto e caixas de combo, da região de arrastar. Espaços vazios e elementos não interativos, como um TextBlock, são arrastáveis por defeito, por isso não precisa de alterar a marcação. Em versões anteriores, o espaço vazio na área de conteúdo podia bloquear o arrastamento da janela. Este comportamento predefinido é a alteração de compatibilidade em tempo de execução TitleBar_ContentDragRegions. Para mais informações, consulte RuntimeCompatibilityOptions.DisabledChanges.

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

O exemplo seguinte baseia-se no exemplo da Galeria do WinUI 3. O conteúdo da barra de título é uma Grid que contém uma AutoSuggestBox e um Button. Ambos os controlos são clicáveis, e o espaço vazio ao lado é 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>

Substituir o comportamento de arrasto de um elemento

Para substituir o comportamento predefinido de um elemento no conteúdo da barra de título, defina a propriedade associada TitleBar.IsDragRegion. A propriedade é um valor booleano que aceita nulo.

Value	Behavior
Não definido (`null`)	O control TitleBar decide. Os controlos interativos são clicáveis e outros elementos são arrastáveis.
`True`	O elemento é arrastável, mesmo que seja um controlo interativo. A entrada de ponteiro no elemento move a janela, por isso os utilizadores não podem clicar no elemento.
`False`	O elemento é clicável, mesmo que não seja um controlo interativo.

Pode definir a propriedade num painel, como um StackPanel:

Se definires para False, toda a área do painel é clicável, incluindo o espaço entre os elementos filhos.
Se definires para True, o painel e os seus filhos são arrastáveis, exceto para os filhos onde defines a propriedade para False.

Defina a propriedade no elemento mais pequeno que precise, para não tornar uma grande área da barra de título arrastável ou clicável por acidente.

Este exemplo torna um conjunto de controlos de formatação clicáveis como um todo, para que os utilizadores não arrastem a janela quando pressionam o espaço entre os controlos.

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

No código, chama SetIsDragRegion para definir o valor e chama ClearValue com IsDragRegionProperty para regressar ao comportamento padrão. Para ler o valor, chame GetIsDragRegion. Retorna null se a propriedade não estiver definida. Quando o valor muda, o controlo TitleBar atualiza as regiões de arrasto.

// 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);

Atualize as regiões de arrastamento quando o conteúdo muda

O controlo TitleBar atualiza as regiões de arrastar quando define ou substitui o seu conteúdo, quando o conteúdo carrega, quando a barra de título muda de tamanho e quando o valor de TitleBar.IsDragRegion muda num elemento.

Se 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 mudar frequentemente, pode definir AutoRefreshDragRegions para True em vez disso. O controlo TitleBar atualiza depois as regiões de arrasto após cada passagem de layout. Esta opção pode afetar o desempenho, por isso está False desativada por defeito.

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

Note

As regiões de arrasto afetam apenas a entrada do apontador. Estas opções não mudam o foco do teclado nem a forma como os clientes de Automatização da Interface de Utilizador, como leitores de ecrã, interagem com os elementos na barra de título. Certifique-se de que os controlos interativos na barra de título ainda podem ser acedidos com o teclado.

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

Comentários

Esta página foi útil?

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