Estilos de XAML

2025-05-01

Você pode personalizar a aparência de seus aplicativos de várias maneiras usando a estrutura XAML. Os estilos permitem definir propriedades de controle e reutilizar essas configurações para uma aparência consistente em vários controles.

WinUI e estilos

A partir do WinUI 2.2, usamos o WinUI para fornecer novas atualizações de estilo visual em nossos componentes de interface do usuário. Se você perceber que a interface do usuário não está atualizando para os mais recentes estilos, certifique-se de atualizar para o pacote NuGet do WinUI mais recente.

A partir do WinUI 2.6, fornecemos novos estilos para a maioria dos controles e um novo sistema de controle de versão que permite reverter para os estilos de controle anteriores, se necessário. Recomendamos que você use os novos estilos, pois eles correspondem melhor à direção de design do Windows. No entanto, se o cenário não puder dar suporte aos novos estilos, as versões anteriores ainda estarão disponíveis.

Você pode alterar a versão de estilo definindo a propriedade ControlsResourcesVersion no XamlControlsResources que você inclui na Application.Resources ao usar o WinUI versão 2. ControlsResourcesVersion tem como padrão o valor de enumeração Version2.

Configurar este valor como Version1 faz com que XamlControlsResources carregue as versões de estilo anteriores, em vez dos novos estilos usados pela versão mais recente do WinUI. Não há suporte para alterar essa propriedade em runtime e a funcionalidade de recarregamento frequente do VisualStudio não funcionará; no entanto, depois de recompilar seu aplicativo, você verá os estilos de controle mudarem.

<Application.Resources>
    <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" 
                           ControlsResourcesVersion="Version1"/>
</Application.Resources>

Noções básicas de estilo

Use estilos para extrair configurações de propriedade visual em recursos reutilizáveis. Aqui está um exemplo que mostra três botões com um estilo que define as propriedades BorderBrush, BorderThickness e Foreground . Aplicando um estilo, você pode fazer com que os controles apareçam iguais sem precisar definir essas propriedades em cada controle separadamente.

Captura de tela de três botões estilosos organizados lado a lado.

Você pode definir um estilo embutido no XAML para um controle ou como um recurso reutilizável. Defina recursos no arquivo XAML de uma página individual, no arquivo App.xaml ou em um arquivo XAML do dicionário de recursos separado. Um arquivo XAML do dicionário de recursos pode ser compartilhado entre aplicativos e mais de um dicionário de recursos pode ser mesclado em um único aplicativo. Onde o recurso é definido determina o escopo no qual ele pode ser usado. Os recursos no nível da página só estão disponíveis na página em que são definidos. Se os recursos com a mesma chave forem definidos em App.xaml e em uma página, o recurso na página substituirá o recurso em App.xaml. Se um recurso for definido em um arquivo de dicionário de recursos separado, seu escopo será determinado pelo local em que o dicionário de recursos é referenciado.

Na definição estilo , você precisa de um atributo TargetType e uma coleção de um ou mais elementos Setter. O atributo TargetType é uma string que especifica um tipo FrameworkElement para aplicar o estilo. O valor do TargetType deve especificar um tipo derivado de FrameworkElementdefinido pelo Windows Runtime ou um tipo personalizado disponível em um assembly referenciado. Se você tentar aplicar um estilo a um controle e o tipo do controle não corresponder ao atributo TargetType do estilo que você está tentando aplicar, ocorrerá uma exceção.

Cada Setter elemento requer uma Propriedade e um Valor. Essas configurações de propriedade indicam a qual propriedade de controle a configuração se aplica e o valor a ser definido para essa propriedade. Você pode definir o Setter.Value com sintaxe de atributo ou de elemento de propriedade. O XAML aqui mostra o estilo aplicado aos botões mostrados anteriormente. Neste XAML, os dois primeiros elementos Setter usam sintaxe de atributo, mas o último Setter, para a propriedade BorderBrush , usa a sintaxe do elemento de propriedade. O exemplo não usa o atributo x:Key, portanto, o estilo é aplicado implicitamente aos botões. A aplicação de estilos implicitamente ou explicitamente é explicada na próxima seção.

<Page.Resources>
    <Style TargetType="Button">
        <Setter Property="BorderThickness" Value="5" />
        <Setter Property="Foreground" Value="Black" />
        <Setter Property="BorderBrush" >
            <Setter.Value>
                <LinearGradientBrush StartPoint="0.5,0" EndPoint="0.5,1">
                    <GradientStop Color="Yellow" Offset="0.0" />
                    <GradientStop Color="Red" Offset="0.25" />
                    <GradientStop Color="Blue" Offset="0.75" />
                    <GradientStop Color="LimeGreen" Offset="1.0" />
                </LinearGradientBrush>
            </Setter.Value>
        </Setter>
    </Style>
</Page.Resources>

<StackPanel Orientation="Horizontal">
    <Button Content="Button"/>
    <Button Content="Button"/>
    <Button Content="Button"/>
</StackPanel>

Aplicar um estilo implícito ou explícito

Se você definir um estilo como um recurso, haverá duas maneiras de aplicá-lo aos seus controles:

Implicitamente, ao especificar apenas um TargetType para o Style.
Explicitamente, especificando um TargetType e um atributo x:Key para o Style e então definindo a propriedade Style do controle de destino com uma extensão de marcação {StaticResource} que utiliza a chave explícita.

Se um estilo contiver o atributo x:Key, você só poderá aplicá-lo a um controle definindo a propriedade Style do controle para o estilo com chave. Por outro lado, um estilo sem um atributo x:Key é aplicado automaticamente a todos os controles do seu tipo de destino, que de outra forma não têm uma configuração de estilo explícita.

Aqui estão dois botões que demonstram estilos implícitos e explícitos.

botões estilizados implicitamente e explicitamente.

Neste exemplo, o primeiro estilo tem um atributo x:Key e seu tipo de destino é Button. A propriedade Style do primeiro botão é definida como essa chave, portanto, esse estilo é aplicado explicitamente. O segundo estilo é aplicado implicitamente ao segundo botão porque seu tipo de destino é Button e o estilo não tem um atributo x:Key.

<Page.Resources>
    <Style x:Key="PurpleStyle" TargetType="Button">
        <Setter Property="FontFamily" Value="Segoe UI"/>
        <Setter Property="FontSize" Value="14"/>
        <Setter Property="Foreground" Value="Purple"/>
    </Style>

    <Style TargetType="Button">
        <Setter Property="FontFamily" Value="Segoe UI"/>
        <Setter Property="FontSize" Value="14"/>
        <Setter Property="RenderTransform">
            <Setter.Value>
                <RotateTransform Angle="25"/>
            </Setter.Value>
        </Setter>
        <Setter Property="BorderBrush" Value="Green"/>
        <Setter Property="BorderThickness" Value="2"/>
        <Setter Property="Foreground" Value="Green"/>
    </Style>
</Page.Resources>

<Grid x:Name="LayoutRoot">
    <Button Content="Button" Style="{StaticResource PurpleStyle}"/>
    <Button Content="Button"/>
</Grid>

Usar estilos baseados em

Para tornar os estilos mais fáceis de manter e otimizar a reutilização de estilo, você pode criar estilos que herdam de outros estilos. Use a propriedade BasedOn para criar estilos herdados. Estilos que herdam de outros estilos devem ter como destino o mesmo tipo de controle ou um controle que deriva do tipo direcionado pelo estilo base. Por exemplo, se um estilo base for direcionado para ContentControl, estilos baseados nesse estilo poderão ser direcionados para ContentControl ou tipos derivados de ContentControl, como Botão e ScrollViewer. Se um valor não for definido no estilo baseado, ele será herdado do estilo base. Para alterar um valor do estilo base, o estilo derivado substitui esse valor. O exemplo a seguir mostra um botão e uma caixa de seleção com estilos que derivam do mesmo estilo base.

botões estilizados usando estilos baseados.

O estilo base tem como destino ContentControl e define as propriedadesHeight e Width. Os estilos baseados nesse estilo têm como alvo a caixa de seleção e o botão , que derivam do ContentControl . Os estilos baseados definem cores diferentes para as propriedades BorderBrush e Foreground . (Normalmente, você não coloca uma borda em torno de uma Caixa de Seleção. Fazemos isso aqui para mostrar os efeitos do estilo.)

<Page.Resources>
    <Style x:Key="BasicStyle" TargetType="ContentControl">
        <Setter Property="Width" Value="130" />
        <Setter Property="Height" Value="30" />
    </Style>

    <Style x:Key="ButtonStyle" TargetType="Button"
           BasedOn="{StaticResource BasicStyle}">
        <Setter Property="BorderBrush" Value="Orange" />
        <Setter Property="BorderThickness" Value="2" />
        <Setter Property="Foreground" Value="Red" />
    </Style>

    <Style x:Key="CheckBoxStyle" TargetType="CheckBox"
           BasedOn="{StaticResource BasicStyle}">
        <Setter Property="BorderBrush" Value="Blue" />
        <Setter Property="BorderThickness" Value="2" />
        <Setter Property="Foreground" Value="Green" />
    </Style>
</Page.Resources>

<StackPanel>
    <Button Content="Button" Style="{StaticResource ButtonStyle}" Margin="0,10"/>
    <CheckBox Content="CheckBox" Style="{StaticResource CheckBoxStyle}"/>
</StackPanel>

Use ferramentas para trabalhar facilmente com estilos

Uma maneira rápida de aplicar estilos aos seus controles é clicar com o botão direito do mouse sobre um controle na superfície de design XAML do Microsoft Visual Studio e selecionar Editar Estilo ou Editar Modelo (dependendo do controle sobre o qual você está clicando). Em seguida, você pode aplicar um estilo existente selecionando Aplicar Recurso ou definir um novo estilo selecionando Criar Vazio. Se você criar um estilo vazio, será dada a opção de defini-lo na página, no arquivo App.xaml ou em um dicionário de recursos separado.

Estilo suave

A substituição dos pincéis do sistema geralmente é feita no nível do aplicativo ou da página e, em ambos os casos, a substituição de cores afetará todos os controles que fazem referência a esse pincel e, em XAML, muitos controles podem referenciar o mesmo pincel do sistema.

<Page.Resources>
    <ResourceDictionary>
        <ResourceDictionary.ThemeDictionaries>
            <ResourceDictionary x:Key="Light">
                 <SolidColorBrush x:Key="ButtonBackground" Color="Transparent"/>
                 <SolidColorBrush x:Key="ButtonForeground" Color="MediumSlateBlue"/>
                 <SolidColorBrush x:Key="ButtonBorderBrush" Color="MediumSlateBlue"/>
            </ResourceDictionary>
        </ResourceDictionary.ThemeDictionaries>
    </ResourceDictionary>
</Page.Resources>

Para estados como PointerOver (o mouse passa o mouse sobre o botão), PointerPressed (o botão foi invocado) ou Desabilitado (o botão não é interacionável). Esses sufixos são acrescentados aos nomes originais do estilo Lightweight: ButtonBackgroundPointerOver, ButtonForegroundPressed, ButtonBorderBrushDisabled, etc. Modificar esses brushes também garantirá que seus controles sejam coloridos de forma consistente com o tema do seu aplicativo.

Colocar essas substituições de pincel no nível App.Resources, alterará todos os botões dentro de todo o aplicativo, em vez de em uma única página.

Estilo por controle

Em outros casos, é desejado alterar um único controle em uma página apenas para ter uma determinada aparência, sem alterar outras versões desse controle:

Captura de tela de três botões estilosos organizados empilhados um em cima do outro.

<CheckBox Content="Normal CheckBox" Margin="5"/>
<CheckBox Content="Special CheckBox" Margin="5">
    <CheckBox.Resources>
        <ResourceDictionary>
            <ResourceDictionary.ThemeDictionaries>
                <ResourceDictionary x:Key="Light">
                    <SolidColorBrush x:Key="CheckBoxForegroundUnchecked"
                        Color="Purple"/>
                    <SolidColorBrush x:Key="CheckBoxForegroundChecked"
                        Color="Purple"/>
                    <SolidColorBrush x:Key="CheckBoxCheckGlyphForegroundChecked"
                        Color="White"/>
                    <SolidColorBrush x:Key="CheckBoxCheckBackgroundStrokeChecked"  
                        Color="Purple"/>
                    <SolidColorBrush x:Key="CheckBoxCheckBackgroundFillChecked"
                        Color="Purple"/>
                </ResourceDictionary>
            </ResourceDictionary.ThemeDictionaries>
        </ResourceDictionary>
    </CheckBox.Resources>
</CheckBox>
<CheckBox Content="Normal CheckBox" Margin="5"/>

Isso só afetaria aquele "Caixa de Seleção Especial" na página em que esse controle existia.

Controles personalizados

Ao criar seus próprios controles personalizados que podem estar alinhados visual e/ou funcionalmente com nossos controles internos, considere usar o estilo implícito e os recursos de estilo Lightweight para definir seu conteúdo personalizado. Você pode usar os recursos diretamente ou criar um novo alias para o recurso.

Usando recursos de controle diretamente

Por exemplo, se você estiver escrevendo um controle semelhante a um Botão, poderá fazer com que seu controle faça referência diretamente aos recursos do botão, desta forma:

<Style TargetType="local:MyCustomControl">
  <Setter Property="Background" Value="{ThemeResource ButtonBackground}" />
  <Setter Property="BorderBrush" Value="{ThemeResource ButtonBorderBrush}" />
</Style>

Controlar recursos de aliasing para novos nomes

Como alternativa, se você preferir criar seus próprios recursos, deverá associar esses nomes personalizados aos nossos recursos de estilização leve padrão.

Por exemplo, o estilo do controle personalizado pode ter definições de recurso especiais:

<Style TargetType="local:MyCustomControl">
  <Setter Property="Background" Value="{ThemeResource MyCustomControlBackground}" />
  <Setter Property="BorderBrush" Value="{ThemeResource MyCustomControlBorderBrush}"/>
</Style>

No Dicionário de Recursos ou na definição principal, você conectaria os recursos de estilo leves aos seus recursos personalizados.

<ResourceDictionary.ThemeDictionaries>
    <ResourceDictionary x:Key="Default">
        <StaticResource x:Key="MyCustomControlBackground" ResourceKey="ButtonBackground" />
        <StaticResource x:Key="MyCustomControlBorderBrush" ResourceKey="ButtonBorderBrush" />
    </ResourceDictionary>        
    <ResourceDictionary x:Key="Light">
        <StaticResource x:Key="MyCustomControlBackground" ResourceKey="ButtonBackground" />
        <StaticResource x:Key="MyCustomControlBorderBrush" ResourceKey="ButtonBorderBrush" />
    </ResourceDictionary>
    <ResourceDictionary x:Key="HighContrast">
        <StaticResource x:Key="MyCustomControlBackground" ResourceKey="ButtonBackground" />
        <StaticResource x:Key="MyCustomControlBorderBrush" ResourceKey="ButtonBorderBrush" />
    </ResourceDictionary>
</ResourceDictionary.ThemeDictionaries>

É necessário que você use uma ThemeDictionary duplicada três vezes para lidar corretamente com as três alterações de tema diferentes (Default, Light, HighContrast).

Cuidado

Se você atribuir um recurso de estilo Lightweight a um novo alias e também redefinir o recurso de estilo Lightweight, sua personalização poderá não ser aplicada se a pesquisa de recurso não estiver na ordem correta. Por exemplo, se você substituir ButtonBackground em um ponto que é pesquisado antes de MyCustomControlBackground ser encontrado, a substituição poderá ser ignorada.

Evite redesenhar os controles

O WinUI 2.2 ou posterior inclui novos estilos e modelos para controles WinUI e do sistema.

A melhor maneira de se manter atualizado com nossos estilos visuais mais recentes é usar o pacote WinUI 2 mais recente e evitar estilos e modelos personalizados (também conhecidos como redirecionamento). Os estilos ainda são uma maneira conveniente de aplicar um conjunto de valores consistentemente entre controles em seu aplicativo. Ao fazer isso, certifique-se de se basear em nossos estilos mais recentes.

Para controles do sistema que usam estilos WinUI (Windows.UI.Xaml.Controls namespace), defina BasedOn="{StaticResource Default<ControlName>Style}", onde <ControlName> está o nome do controle. Por exemplo:

<Style TargetType="TextBox" BasedOn="{StaticResource DefaultTextBoxStyle}">
    <Setter Property="Foreground" Value="Blue"/>
</Style>

Para controles WinUI 2 (Microsoft.UI.Xaml.Controls namespace), o estilo padrão é definido nos metadados, portanto, omita BasedOn.

Controles derivados

Se você derivar um controle personalizado de um controle XAML existente, ele não obterá os estilos WinUI 2 por padrão. Para aplicar os estilos WinUI 2:

Crie um novo Style com o TargetType definido como seu controle personalizado.
Baseie o Estilo no estilo padrão do controle do qual você derivava.

Um cenário comum para isso é derivar um novo controle a partir do ContentDialog. Este exemplo mostra como criar um novo estilo que aplica a cor DefaultContentDialogStyle à sua caixa de diálogo personalizada.

<ContentDialog
    x:Class="ExampleApp.SignInContentDialog"
    ... >

    <ContentDialog.Resources>
        <Style TargetType="local:SignInContentDialog" BasedOn="{StaticResource DefaultContentDialogStyle}"/>
        ...
    </ContentDialog.Resources> 
    <!-- CONTENT -->
</ContentDialog>

A propriedade de modelo

Um setter de estilo pode ser usado para a propriedade Template de um Controle, na verdade, isso constitui a maior parte de um estilo XAML típico e dos recursos XAML de um aplicativo. Isso é discutido com mais detalhes nos modelos de controle do tópico.