Personalização da barra de título

O Windows fornece uma barra de título padrão para cada janela e permite personalizá-la para corresponder à personalidade do aplicativo. A barra de título padrão vem com alguns componentes padrão e funcionalidade principal, como arrastar e redimensionar a janela.

Consulte o artigo de design da Barra de título para obter diretrizes sobre como personalizar a barra de título do aplicativo, o conteúdo aceitável da barra de título e os padrões de interface do usuário recomendados.

Componentes da barra de título

Esta lista descreve os componentes da barra de título padrão.

• Retângulo da barra de título
• Texto do título
• Menu do sistema – acessado clicando no ícone do aplicativo ou clicando com o botão direito do mouse na barra de título
• Controles de legenda
  • Botão Minimizar
  • Botão Maximizar/Restaurar
  • Botão Fechar

Em aplicativos UWP, você pode personalizar a barra de título usando membros das classes ApplicationView e CoreApplicationView. Há várias APIs para modificar progressivamente a aparência da barra de título com base no nível de personalização necessário.

Quanto personalizar a barra de título

Há dois níveis de personalização que você pode aplicar à barra de título: aplicar pequenas modificações à barra de título padrão ou estender a tela do aplicativo para a área da barra de título e fornecer conteúdo completamente personalizado.

Simples

Para personalização simples, como alterar a cor da barra de título, você pode definir propriedades no objeto da barra de título da janela do aplicativo para especificar as cores que deseja usar para elementos da barra de título. Nesse caso, o sistema mantém responsabilidade de todos os outros aspectos da barra de título, como o título do aplicativo de desenho e definindo áreas para arrastar.

Completo

A outra opção é ocultar a barra de título padrão e substituí-la com seu próprio conteúdo personalizado. Por exemplo, você pode colocar texto, uma caixa de pesquisa ou menus personalizados na área da barra de título. Você também precisará usar essa opção para estender um fundo de material, como Mica, na área da barra de título.

Quando você optar por personalização completa, você é responsável por colocar o conteúdo na área de barra de título, e você pode definir sua própria região para arrastar. Os controles de legenda (botões Fechar, Minimizar e Maximizar o sistema) ainda estão disponíveis e são manipulados pelo sistema, mas não são como elementos, como o título do aplicativo. Você mesmo precisará criar esses elementos, conforme necessário, para seu aplicativo.

Personalização simples

Se quiser personalizar apenas as cores ou o ícone da barra de título, você pode definir propriedades no objeto da barra de título para a janela do aplicativo.

Título

Por padrão, a barra de título mostra o nome de exibição do aplicativo como o título da janela. O nome de exibição definido no arquivo Package.appxmanifest.

Para adicionar texto personalizado ao título, defina a propriedade ApplicationView.Title como um valor de texto, conforme mostrado aqui.

public MainPage()
{
    this.InitializeComponent();

    ApplicationView.GetForCurrentView().Title = "Custom text";
}

Seu texto é anexado ao título da janela, que será exibido como “texto personalizado - nome de exibição do aplicativo”. Para mostrar um título personalizado sem o nome de exibição do aplicativo, você precisa substituir a barra de título padrão, conforme mostrado na seção Personalização completa.

Cores

Este exemplo mostra como obter uma instância de ApplicationViewTitleBar e definir suas propriedades de cor.

Este código pode ser colocado no método OnLaunched (App.xaml.cs) do aplicativo, após a chamada para Window.Activate, ou na primeira página do aplicativo.

// using Windows.UI;
// using Windows.UI.ViewManagement;

var titleBar = ApplicationView.GetForCurrentView().TitleBar;

// Set active window colors
titleBar.ForegroundColor = Colors.White;
titleBar.BackgroundColor = Colors.Green;
titleBar.ButtonForegroundColor = Colors.White;
titleBar.ButtonBackgroundColor = Colors.SeaGreen;
titleBar.ButtonHoverForegroundColor = Colors.White;
titleBar.ButtonHoverBackgroundColor = Colors.DarkSeaGreen;
titleBar.ButtonPressedForegroundColor = Colors.Gray;
titleBar.ButtonPressedBackgroundColor = Colors.LightGreen;

// Set inactive window colors
titleBar.InactiveForegroundColor = Colors.Gainsboro;
titleBar.InactiveBackgroundColor = Colors.SeaGreen;
titleBar.ButtonInactiveForegroundColor = Colors.Gainsboro;
titleBar.ButtonInactiveBackgroundColor = Colors.SeaGreen;

Há alguns aspectos a serem observados ao definir as cores da barra de título:

• A cor de fundo do botão não é aplicada ao botão Fechar quando você passa o mouse sobre ele ou clica nele. O botão fechar sempre usa a cor definida pelo sistema para esses estados.
• Definir uma propriedade de cor para null restaura a cor padrão do sistema.
• Não é possível definir cores transparentes. O canal alfa da cor é ignorado.

O Windows oferece ao usuário a opção de aplicar a cor de destaque selecionada à barra de título. Se você definir qualquer cor da barra de título, recomendamos que você defina explicitamente todas as cores. Isso garante que não haja combinações de cores não intencionais que ocorram devido às configurações de cores definidas pelo usuário.

Personalização completa

Quando você concorda com a personalização da barra de título completa, a área de cliente do seu aplicativo é estendida para cobrir toda a janela, incluindo a área da barra de título. Você é responsável por desenho e manipulação de entrada para toda a janela, exceto os botões de legenda, que são sobrepostos na parte superior da tela do aplicativo.

Para ocultar a barra de título padrão e estender seu conteúdo para a área da barra de título, defina a propriedade ExtendViewIntoTitleBar como true. Você pode definir essa propriedadeno método do aplicativo OnLaunched (App.xaml.cs) ou na primeira página do aplicativo.

Este exemplo mostra como obter a propriedade CoreApplicationViewTitleBar e definir a propriedadeExtendViewIntoTitleBar como true.

using Windows.ApplicationModel.Core;

public MainPage()
{
    this.InitializeComponent();

    // Hide default title bar.
    var coreTitleBar = CoreApplication.GetCurrentView().TitleBar;
    coreTitleBar.ExtendViewIntoTitleBar = true;
}

Conteúdo da barra de título e regiões de arrastar

Quando seu aplicativo é estendido para a área da barra de título, você é responsável por definir e gerenciar a interface do usuário para a barra de título. Normalmente, isso inclui, no mínimo, a especificação do texto do título e da região de arrastar. A região de arrastar da barra de título define onde o usuário pode clicar e arrastar para mover a janela. Também é onde o usuário pode clicar com o botão direito do mouse para mostrar o menu do sistema.

Para saber mais sobre o conteúdo aceitável da barra de título e os padrões de interface do usuário recomendados, consulte Design da barra de título.

Você especifica a região de arrastar chamando o método Window.SetTitleBar e passando um UIElement que define a região de arrastar. (O UIElement é normalmente um painel que contém outros elementos.) A propriedade ExtendViewIntoTitleBar deve ser definida como true para que a chamada para SetTitleBar tenha algum efeito.

Veja como definir um Grid de conteúdo como a região da barra de título arrastável. Esse código vai no XAML e code-behind para a primeira página do seu aplicativo.

<Grid x:Name="AppTitleBar" Background="Transparent">
    <!-- Width of the padding columns is set in LayoutMetricsChanged handler. -->
    <!-- Using padding columns instead of Margin ensures that the background
         paints the area under the caption control buttons (for transparent buttons). -->
    <Grid.ColumnDefinitions>
        <ColumnDefinition x:Name="LeftPaddingColumn" Width="0"/>
        <ColumnDefinition/>
        <ColumnDefinition x:Name="RightPaddingColumn" Width="0"/>
    </Grid.ColumnDefinitions>
    <Image Source="Assets/WindowIcon.png" 
           Grid.Column="1"
           HorizontalAlignment="Left"
           Width="16" Height="16"
           Margin="8,0,0,0"/>
    <TextBlock x:Name="AppTitleTextBlock"
               Text="App title" 
               Style="{StaticResource CaptionTextBlockStyle}" 
               Grid.Column="1"
               VerticalAlignment="Center"
               Margin="28,0,0,0"/>
</Grid>

public MainPage()
{
    this.InitializeComponent();

    var coreTitleBar = CoreApplication.GetCurrentView().TitleBar;
    coreTitleBar.ExtendViewIntoTitleBar = true;

    // Set XAML element as a drag region.
    Window.Current.SetTitleBar(AppTitleBar);
}

Por padrão, a barra de título do sistema mostra o nome de exibição do aplicativo como o título da janela. O nome de exibição é definido no arquivo Package.appxmanifest. Você pode obter esse valor e usá-lo em sua barra de título personalizada como esta.

AppTitleTextBlock.Text = AppInfo.Current.DisplayInfo.DisplayName;

Conteúdo interativo

Você pode colocar controles interativos, como botões, menus ou uma caixa de pesquisa, na parte superior do aplicativo para que eles pareçam estar na barra de título. No entanto, você precisa seguir algumas regras para garantir que os elementos interativos recebam a entrada do usuário e, ao mesmo tempo, permitir que os usuários movam sua janela.

• Você deve chamar SetTitleBar para definir uma área como a região da barra de título arrastável. Caso contrário, o sistema define a parte superior da página como a região de arrastar padrão. O sistema irá então lidar com todas as entradas de usuário para esta área e impedir que a entrada chegue aos seus controles.
• Coloque seus controles interativos sobre a parte superior da região de arrastar definida pela chamada para SetTitleBar (com uma ordem z mais alta). Não faça com que seus controles interativos filhos do UIElement sejam passados para SetTitleBar. Depois de passar um elemento para SetTitleBar, o sistema o trata como a barra de título do sistema e identifica todas as entradas de ponteiro para esse elemento.

Aqui, o elemento AutoSuggestBox tem uma ordem z mais alta do que AppTitleBar, portanto, ele recebe a entrada do usuário.

<Grid>
    <Grid.RowDefinitions>
        <RowDefinition Height="48"/>
        <RowDefinition/>
    </Grid.RowDefinitions>
    <Grid x:Name="AppTitleBar" Background="Transparent">
        <!-- Width of the padding columns is set in LayoutMetricsChanged handler. -->
        <!-- Using padding columns instead of Margin ensures that the background
             paints the area under the caption control buttons (for transparent buttons). -->
        <Grid.ColumnDefinitions>
            <ColumnDefinition x:Name="LeftPaddingColumn" Width="0"/>
            <ColumnDefinition/>
            <ColumnDefinition x:Name="RightPaddingColumn" Width="0"/>
        </Grid.ColumnDefinitions>
        <Image Source="Assets/WindowIcon.png" 
               Grid.Column="1"
               HorizontalAlignment="Left"
               Width="16" Height="16"
               Margin="8,0,0,0"/>
        <TextBlock x:Name="AppTitleTextBlock"
                   Text="App title" 
                   Style="{StaticResource CaptionTextBlockStyle}" 
                   Grid.Column="1"
                   VerticalAlignment="Center"
                   Margin="28,0,0,0"/>
    </Grid>

    <!-- This control has a higher z-order than AppTitleBar, 
         so it receives user input. -->
    <AutoSuggestBox QueryIcon="Find"
                    PlaceholderText="Search"
                    HorizontalAlignment="Center"
                    Width="260" Height="32"/>
</Grid>

Botões de legenda do sistema

O sistema reserva o canto superior esquerdo ou direito superior da janela do aplicativo para os botões de legenda do sistema (minimizar, maximizar, fechar). O sistema mantém o controle da área do botão de legenda para garantir que a funcionalidade mínima seja fornecida para arrastar, minimizar, maximizar e fechar a janela. O sistema desenha o botão Fechar no canto superior direito para idiomas da esquerda para a direita e no canto superior esquerdo para idiomas da direita para a esquerda.

Você pode desenhar conteúdo sob a área de controle de legenda definida por essas propriedades, como seu plano de fundo do aplicativo, mas você não deve colocar qualquer interface do usuário com a qual você espera que o usuário possa interagir. Ela não recebe nenhuma entrada porque a entrada para os controles de legenda é manipulada pelo sistema.

Essas linhas do exemplo anterior mostram as colunas de preenchimento no XAML que define a barra de título. O uso de colunas de preenchimento em vez de margens garante que a tela de fundo pinte a área sob os botões de controle legenda (para botões transparentes). Usar colunas de preenchimento direita e esquerda garante que sua barra de título se comporte corretamente nos layouts da direita para a esquerda e da esquerda para a direita.

<Grid.ColumnDefinitions>
    <ColumnDefinition x:Name="LeftPaddingColumn" Width="0"/>
    <ColumnDefinition/>
    <ColumnDefinition x:Name="RightPaddingColumn" Width="0"/>
</Grid.ColumnDefinitions>

A dimensão e a posição da área de controle de legenda é comunicada pela classe CoreApplicationViewTitleBar para que você possa considerá-la no layout de sua interface do usuário da barra de títulos. A largura da região reservada em cada lado é determinada pelas propriedades SystemOverlayLeftInset ou SystemOverlayRightInset e a altura é determinado pela propriedade Altura.

Você pode manipular o evento LayoutMetricsChanged para responder a alterações no tamanho dos botões de título. Por exemplo, isso pode acontecer se o layout do aplicativo mudar de da esquerda para a direita para da direita para a esquerda. Manipule esse evento para verificar e atualizar o posicionamento dos elementos da interface do usuário que dependem do tamanho da barra de título.

Este exemplo mostra como ajustar o layout da barra de título para levar em conta as alterações nas métricas da barra de título. AppTitleBar, LeftPaddingColumn e RightPaddingColumn são declarados no XAML mostrado anteriormente.

private void CoreTitleBar_LayoutMetricsChanged(CoreApplicationViewTitleBar sender, object args)
{
    // Get the size of the caption controls and set padding.
    LeftPaddingColumn.Width = new GridLength(coreTitleBar.SystemOverlayLeftInset);
    RightPaddingColumn.Width = new GridLength(coreTitleBar.SystemOverlayRightInset);
}

Cor e transparência nos botões de legenda

Ao estender o conteúdo do aplicativo para a área da barra de título, você pode tornar a tela de fundo dos botões de legenda transparente para permitir que a tela de fundo do aplicativo seja exibida. Você normalmente define o plano de fundo como Colors.Transparent para transparência total. Para transparência parcial, defina o canal alfa para a Cor para a qual você definiu a cor.

Estas propriedades da barra de título podem ser transparentes:

• ButtonBackgroundColor
• ButtonHoverBackgroundColor
• ButtonPressedBackgroundColor
• ButtonInactiveBackgroundColor

Todas as outras propriedades de cor continuarão a ignorar o canal alfa. Se ExtendViewIntoTitleBar estiver definido como false, o canal alfa será sempre ignorado para todas as propriedades de cor ApplicationViewTitleBar.

A cor de fundo do botão não é aplicada ao botão Fechar quando você passa o mouse sobre ele ou clica nele. O botão fechar sempre usa a cor definida pelo sistema para esses estados.

Diminua a barra de título quando a janela estiver inativa

Você deve deixar claro quando a janela está ativa ou inativa. No mínimo, você deve alterar a cor dos botões na barra de título, ícones e texto.

Identifique o evento CoreWindow.Activated para determinar o estado de ativação da janela e atualize a interface do usuário da barra de título conforme necessário.

public MainPage()
{
    ...
    Window.Current.CoreWindow.Activated += CoreWindow_Activated;
}

private void CoreWindow_Activated(CoreWindow sender, WindowActivatedEventArgs args)
{
    UISettings settings = new UISettings();
    if (args.WindowActivationState == CoreWindowActivationState.Deactivated)
    {
        AppTitleTextBlock.Foreground = 
            new SolidColorBrush(settings.UIElementColor(UIElementType.GrayText));
    }
    else
    {
        AppTitleTextBlock.Foreground = 
            new SolidColorBrush(settings.UIElementColor(UIElementType.WindowText));
    }
}

Redefinir a barra de título

Você pode chamar SetTitleBar para alternar para um novo elemento de barra de título enquanto seu aplicativo está em execução. Você também pode passar null como o parâmetro para SetTitleBar e definir ExtendViewIntoTitleBar para reverter para false a barra de título padrão do sistema.

Mostrar e ocultar a barra de título

Se você adicionar suporte para modos de sobreposição compacta ou de tela inteira ao seu aplicativo, talvez seja necessário fazer alterações na barra de título quando o aplicativo alternar entre esses modos.

Quando seu aplicativo é executado em tela inteira ou modo tablet (somente Windows 10), o sistema oculta a barra de título e os botões do controle de legenda. No entanto, o usuário pode invocar a barra de título para mostrá-la como uma sobreposição na parte superior da interface do usuário do aplicativo.

Você pode identificar o evento CoreApplicationViewTitleBar.IsVisibleChanged para ser notificado quando a barra de título estiver oculta ou invocada e mostrar ou ocultar o conteúdo da barra de título personalizada, conforme necessário.

Este exemplo mostra como identificar o evento IsVisibleChanged para mostrar e ocultar o elemento AppTitleBar de exemplos anteriores.

public MainPage()
{
    this.InitializeComponent();

    var coreTitleBar = CoreApplication.GetCurrentView().TitleBar;

    // Register a handler for when the title bar visibility changes.
    // For example, when the title bar is invoked in full screen mode.
    coreTitleBar.IsVisibleChanged += CoreTitleBar_IsVisibleChanged;
}

private void CoreTitleBar_IsVisibleChanged(CoreApplicationViewTitleBar sender, object args)
{
    if (sender.IsVisible)
    {
        AppTitleBar.Visibility = Visibility.Visible;
    }
    else
    {
        AppTitleBar.Visibility = Visibility.Collapsed;
    }
}

O que fazer e o que não fazer

• Deixe claro quando a janela está ativa ou inativa. No mínimo, altere a cor do texto, dos ícones e dos botões na barra de título.
• Defina uma região de arrastar ao longo da borda superior da tela do aplicativo. Combinar o posicionamento das barras de título do sistema facilita a localização pelos usuários.
• Defina uma região de arrastar que corresponde a barra de título visual (se houver) na tela do aplicativo.

Exemplo de personalização completa

Este exemplo mostra todo o código descrito na seção Personalização completa.

<Page
    x:Class="WinUI2_ExtendedTitleBar.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:WinUI2_ExtendedTitleBar"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"
    xmlns:muxc="using:Microsoft.UI.Xaml.Controls"
    muxc:BackdropMaterial.ApplyToRootOrPageBackground="True">
    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition Height="48"/>
            <RowDefinition/>
        </Grid.RowDefinitions>
        <Grid x:Name="AppTitleBar" Background="Transparent">
            <!-- Width of the padding columns is set in LayoutMetricsChanged handler. -->
            <!-- Using padding columns instead of Margin ensures that the background
                 paints the area under the caption control buttons (for transparent buttons). -->
            <Grid.ColumnDefinitions>
                <ColumnDefinition x:Name="LeftPaddingColumn" Width="0"/>
                <ColumnDefinition/>
                <ColumnDefinition x:Name="RightPaddingColumn" Width="0"/>
            </Grid.ColumnDefinitions>
            <Image Source="Assets/WindowIcon.png" 
                   Grid.Column="1"
                   HorizontalAlignment="Left"
                   Width="16" Height="16"
                   Margin="8,0,0,0"/>
            <TextBlock x:Name="AppTitleTextBlock"
                       Text="App title" 
                       Style="{StaticResource CaptionTextBlockStyle}" 
                       Grid.Column="1"
                       VerticalAlignment="Center"
                       Margin="28,0,0,0"/>
        </Grid>

        <!-- This control has a higher z-order than AppTitleBar, 
             so it receives user input. -->
        <AutoSuggestBox QueryIcon="Find"
                        PlaceholderText="Search"
                        HorizontalAlignment="Center"
                        Width="260" Height="32"/>

        <muxc:NavigationView Grid.Row="1"
                             IsBackButtonVisible="Collapsed"
                             IsSettingsVisible="False">
            <StackPanel>
                <TextBlock Text="Content" 
                           Style="{ThemeResource TitleTextBlockStyle}"
                           Margin="12,0,0,0"/>
            </StackPanel>
        </muxc:NavigationView>
    </Grid>
</Page>

public MainPage()
{
    this.InitializeComponent();

    // Hide default title bar.
    CoreApplicationViewTitleBar coreTitleBar = 
        CoreApplication.GetCurrentView().TitleBar;
    coreTitleBar.ExtendViewIntoTitleBar = true;

    // Set caption buttons background to transparent.
    ApplicationViewTitleBar titleBar = 
        ApplicationView.GetForCurrentView().TitleBar;
    titleBar.ButtonBackgroundColor = Colors.Transparent;

    // Set XAML element as a drag region.
    Window.Current.SetTitleBar(AppTitleBar);

    // Register a handler for when the size of the overlaid caption control changes.
    coreTitleBar.LayoutMetricsChanged += CoreTitleBar_LayoutMetricsChanged;

    // Register a handler for when the title bar visibility changes.
    // For example, when the title bar is invoked in full screen mode.
    coreTitleBar.IsVisibleChanged += CoreTitleBar_IsVisibleChanged;

    // Register a handler for when the window activation changes.
    Window.Current.CoreWindow.Activated += CoreWindow_Activated;
}

private void CoreTitleBar_LayoutMetricsChanged(CoreApplicationViewTitleBar sender, object args)
{
    // Get the size of the caption controls and set padding.
    LeftPaddingColumn.Width = new GridLength(coreTitleBar.SystemOverlayLeftInset);
    RightPaddingColumn.Width = new GridLength(coreTitleBar.SystemOverlayRightInset);
}

private void CoreTitleBar_IsVisibleChanged(CoreApplicationViewTitleBar sender, object args)
{
    if (sender.IsVisible)
    {
        AppTitleBar.Visibility = Visibility.Visible;
    }
    else
    {
        AppTitleBar.Visibility = Visibility.Collapsed;
    }
}

 private void CoreWindow_Activated(CoreWindow sender, WindowActivatedEventArgs args)
 {
     UISettings settings = new UISettings();
     if (args.WindowActivationState == CoreWindowActivationState.Deactivated)
     {
         AppTitleTextBlock.Foreground = 
            new SolidColorBrush(settings.UIElementColor(UIElementType.GrayText));
     }
     else
     {
         AppTitleTextBlock.Foreground = 
            new SolidColorBrush(settings.UIElementColor(UIElementType.WindowText));
     }
 }

Artigos relacionados

• Personalização da barra de título (SDK do Aplicativo Windows)
• Acrílico
• Mica
• Cor