Estilos XAML

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

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

A partir da 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 combinam melhor com a direção de design do Windows. No entanto, se o seu cenário não puder suportar os 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 em seu Application.Resources quando você usa WinUI versão 2. ControlsResourcesVersion assume como padrão o valor de enum Version2.

Definir esse 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 tempo de execução e a funcionalidade de recarga a quente do VisualStudio não funcionará; No entanto, depois de reconstruir 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 3 botões com um estilo que define as propriedades de BorderBrush , BorderThickness e Foreground . Ao aplicar um estilo, você pode fazer com que os controles pareçam iguais sem ter que definir essas propriedades em cada controle separadamente.

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 de dicionário de recursos separado. Um arquivo XAML de dicionário de recursos pode ser compartilhado entre aplicativos e mais de um dicionário de recursos pode ser mesclado em um único aplicativo. O local onde o recurso é definido determina o âmbito em que pode ser utilizado. Os recursos ao nível da página estão disponíveis apenas na página onde estã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 onde o dicionário de recursos é referenciado.

Na definição de Estilo , você precisa de um atributo TargetType e uma coleção de um ou mais elementos Setter. O atributo TargetType é uma cadeia de texto que especifica um tipo de FrameworkElement ao qual o estilo será aplicado. O valor de TargetType deve especificar um FrameworkElementtipo derivado definido pelo Tempo de Execução do Windows 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 elemento Setter 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 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 sintaxe de elemento de propriedade. O exemplo não usa o atributo x:Key atributo, portanto, o estilo é aplicado implicitamente aos botões. A aplicação de estilos implícita 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, há duas maneiras de aplicá-lo aos seus controles:

• Implicitamente, especificando apenas um TargetType para o Style.
• Explicitamente, especificando um TargetType e um atributo x:Key para o Style e, em seguida, definindo a propriedade Style do controle de destino com uma referência de 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 como o estilo chaveado. Por outro lado, um estilo sem um atributo x:Key é aplicado automaticamente a cada controlo do seu tipo de destino, caso este não tenha uma configuração de estilo explícita.

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

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 facilitar a manutenção de estilos e otimizar a reutilização de estilos, você pode criar estilos que herdam de outros estilos. Use a propriedade BasedOn para criar estilos herdados. Os 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 tiver como destino ContentControl, os estilos baseados nesse estilo podem ter como destino ContentControl ou tipos que derivam de ContentControl, como Button e ScrollViewer. Se um valor não for definido no estilo baseado, ele será herdado do estilo base. Para modificar um valor do estilo base, o estilo que é baseado nele substitui esse valor. O próximo exemplo mostra um Button e um CheckBox com estilos que herdam do mesmo estilo base.

O estilo base tem como destino ContentControle define as propriedades Heighte Width. Os estilos baseados neste estilo têm como alvo CheckBox e Button, que derivam de ContentControl. Os estilos baseados definem cores diferentes para as propriedades BorderBrush e Foreground . (Normalmente, você não coloca uma borda ao redor 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 com estilos facilmente

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

Estilo leve

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 cor afetará todos os controles que fazem referência a esse pincel – e em XAML muitos controles podem fazer referência ao 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 rato está sobre o botão), PointerPressed (botão foi invocado) ou Disabled (botão não é interativo). Esses sufixos são aplicados aos nomes originais de estilo leve: ButtonBackgroundPointerOver, ButtonForegroundPressed, ButtonBorderBrushDisabled, etc. Modificar esses Brushes também garantirá que os seus controlos sejam coloridos de forma consistente com o tema da sua aplicação.

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

Estilo por controle

Em outros casos, alterar um único controle em uma página apenas para parecer de uma determinada maneira, sem alterar quaisquer outras versões desse controle, é desejado:

<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 afetaria apenas uma "Caixa de seleção especial" na página onde esse controle existia.

Controlos personalizados

Quando você estiver criando seus próprios controles personalizados que podem estar visualmente e/ou funcionalmente alinhados com nossos controles internos, considere o uso de estilo implícito e recursos de estilo leve 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 que se parece com um botão, você pode fazer com que seu controle faça referência aos recursos do botão diretamente, desta forma:

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

Atribuição de nomes alternativos a recursos de controlo novos

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

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

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

No seu Dicionário de Recursos ou definição principal, você conectaria os recursos de estilo Lightweight 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 utilizes um ThemeDictionary que é duplicado três vezes para lidar corretamente com as três diferentes alterações de tema (Default, Light, HighContrast).

Evite reestilizar controles

O WinUI 2.2 ou posterior inclui novos estilos e modelos para WinUI e controles 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 re-modelagem). Os estilos ainda são uma maneira conveniente de aplicar um conjunto de valores de forma consistente entre os controles em seu aplicativo. Ao fazer isso, certifique-se de se basear em nossos estilos mais recentes.

Para controles de sistema que usam estilos WinUI (Windows.UI.Xaml.Controls namespace), defina BasedOn="{StaticResource Default<ControlName>Style}", onde <ControlName> é 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.

Controlos 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 de estilo de com seu TargetType definido para seu controle personalizado.
• Baseie o Style no estilo padrão do controle do qual você derivou.

Um cenário comum para isso é derivar um novo controlo de ContentDialog. Este exemplo mostra como criar um novo estilo que aplique o valor 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 template

Um configurador de estilo pode ser usado para a propriedade Template de um Controlee, na verdade, isso constitui a maior parte de um estilo XAML típico e dos recursos XAML de uma aplicação. Isso é discutido com mais detalhes no tópico Modelos de controle.