Recursos de tema XAML

Recursos de tema em XAML são um conjunto de recursos que aplicam valores diferentes dependendo de qual tema do sistema está ativo. Há 3 temas que a estrutura XAML suporta: "Light", "Dark" e "HighContrast".

Pré-requisitos: Este tópico pressupõe que você tenha lido referências de recursos ResourceDictionary e XAML.

Recursos temáticos v. recursos estáticos

Há duas extensões de marcação XAML que podem fazer referência a um recurso XAML de um dicionário de recursos XAML existente: {StaticResource} markup extension e {ThemeResource} markup extension.

A avaliação de uma extensão de marcação {ThemeResource} ocorre quando o aplicativo é carregado e, posteriormente, cada vez que o tema é alterado em tempo de execução. Isso geralmente é o resultado de o usuário alterar as configurações do dispositivo ou de uma alteração programática dentro do aplicativo que altera seu tema atual.

Por outro lado, uma extensão de marcação {StaticResource} é avaliada somente quando o XAML é carregado pela primeira vez pelo aplicativo. Ele não é atualizado. É semelhante a uma localização e substituição em seu XAML com o valor de tempo de execução real na inicialização do aplicativo.

Recursos temáticos na estrutura do dicionário de recursos

Cada recurso de tema faz parte do arquivo XAML themeresources.xaml. Para fins de design, themeresources.xaml está disponível na pasta \(Arquivos de Programas)\Windows Kits\10\DesignTime\CommonConfiguration\Neutral\UAP\<SDK version>\Generic de uma instalação do Windows Software Development Kit (SDK). Os dicionários de recursos em themeresources.xaml também são reproduzidos em generic.xaml no mesmo diretório.

O Tempo de Execução do Windows não usa esses arquivos físicos para pesquisa de tempo de execução. É por isso que eles estão especificamente em uma pasta DesignTime e não são copiados para aplicativos por padrão. Em vez disso, esses dicionários de recursos existem na memória como parte do próprio Tempo de Execução do Windows, e as referências de recursos XAML do seu aplicativo a recursos de tema (ou recursos do sistema) são resolvidas lá no tempo de execução.

Diretrizes para recursos de tema personalizados

Siga estas diretrizes ao definir e consumir seus próprios recursos de tema personalizados:

• Especifique dicionários temáticos para "Light" e "Dark", além do seu dicionário "HighContrast". Embora você possa criar um ResourceDictionary com "Default" como chave, é preferível ser explícito e, em vez disso, usar "Light", "Dark" e "HighContrast".

• Use a extensão de marcação {ThemeResource} em: Estilos, Setters, Modelos de controle, Setters de propriedade e Animações.

• Não use a extensão de marcação {ThemeResource} em suas definições de recursos dentro de seus ThemeDictionaries. Em vez disso, use a extensão de marcação {StaticResource} .

  EXCEÇÃO: Você pode usar a extensão de marcação {ThemeResource} para fazer referência a recursos que são agnósticos ao tema do aplicativo em seus ThemeDictionaries. Exemplos desses recursos são recursos de cor de destaque como SystemAccentColor, ou recursos de cor do sistema, que normalmente são prefixados com "SystemColor" como SystemColorButtonFaceColor.

A rampa de cores XAML e os pincéis dependentes do tema

O conjunto combinado de cores para temas "Light", "Dark" e "HighContrast" compõem a rampa de cores do Windows em XAML. Se você deseja modificar os temas do sistema ou aplicar um tema aos seus próprios elementos XAML, é importante entender como os recursos de cores são estruturados.

Para obter informações adicionais sobre como aplicar cores em seu aplicativo do Windows, consulte Cor em aplicativos do Windows.

Cores do tema claro e escuro

A estrutura XAML fornece um conjunto de recursos de Cor nomeados com valores adaptados para os temas "Claro" e "Escuro". Para WinUI 2, os recursos de tema são definidos no arquivo Xaml de recursos de tema comuns. Os nomes de cores são muito descritivos de seu uso pretendido, e há um recurso SolidColorBrush correspondente para cada recurso de cor.

O aplicativo WinUI 3 Gallery inclui exemplos interativos da maioria dos controles, recursos e funcionalidades do WinUI 3. Obtenha o aplicativo da Microsoft Store ou obtenha o código-fonte no GitHub

Cores do tema de contraste do sistema Windows

Além do conjunto de recursos fornecidos pela estrutura XAML, há um conjunto de valores de cores derivados da paleta do sistema Windows. Essas cores não são específicas do Tempo de Execução do Windows ou dos aplicativos do Windows. No entanto, muitos dos recursos do Pincel XAML consomem essas cores quando o sistema está operando (e o aplicativo está em execução) usando o tema "HighContrast". A estrutura XAML fornece essas cores em todo o sistema como recursos chaveados. As teclas seguem o formato de nomenclatura: SystemColor[name]Color.

Para obter mais informações sobre como dar suporte a temas de contraste, consulte Temas de contraste.

Cor de destaque do sistema

Além das cores do tema de contraste do sistema, a cor de destaque do sistema é fornecida como um recurso de cor especial usando a tecla SystemAccentColor. No tempo de execução, esse recurso obtém a cor que o usuário especificou como a cor de destaque nas configurações de personalização do Windows.

Pincéis dependentes do tema

Os recursos de cor mostrados nas seções anteriores são usados para definir a propriedade Color dos recursos SolidColorBrush nos dicionários de recursos do tema do sistema. Use os recursos de pincel para aplicar a cor a elementos XAML.

Vamos ver como o valor de cor para este pincel é determinado em tempo de execução. Nos dicionários de recursos "Luz" e "Escuro", este pincel é definido assim:

<SolidColorBrush x:Key="TextFillColorPrimaryBrush" Color="{StaticResource TextFillColorPrimary}"/>

No dicionário de recursos "HighContrast", este pincel é definido assim:

<SolidColorBrush x:Key="TextFillColorPrimaryBrush" Color="{ThemeResource SystemColorWindowTextColor}"/>

Quando esse pincel é aplicado a um elemento XAML, sua cor é determinada em tempo de execução pelo tema atual, conforme mostrado nesta tabela.

A rampa de tipo XAML

O arquivo themeresources.xaml define vários recursos que definem um Style que você pode aplicar a contêineres de texto em sua interface do usuário, especificamente para TextBlock ou RichTextBlock. Estes não são os estilos implícitos padrão. Eles são fornecidos para facilitar a criação de definições de interface do usuário XAML que correspondam à rampa de tipos do Windows documentada em Diretrizes para fontes.

Esses estilos são para atributos de texto que você deseja aplicar a todo o contêiner de texto. Se desejar que os estilos sejam aplicados apenas a seções do texto, defina atributos nos elementos de texto dentro do contêiner, como em uma Execução em TextBlock.Inlines ou em um Parágrafo em RichTextBlock.Blocks.

Os estilos têm esta aparência quando aplicados a um TextBlock:

<TextBlock Text="Caption" Style="{StaticResource CaptionTextBlockStyle}"/>
<TextBlock Text="Body" Style="{StaticResource BodyTextBlockStyle}"/>
<TextBlock Text="Body Strong" Style="{StaticResource BodyStrongTextBlockStyle}"/>
<TextBlock Text="Body Large" Style="{StaticResource BodyLargeTextBlockStyle}"/>
<TextBlock Text="Subtitle" Style="{StaticResource SubtitleTextBlockStyle}"/>
<TextBlock Text="Title" Style="{StaticResource TitleTextBlockStyle}"/>
<TextBlock Text="Title Large" Style="{StaticResource TitleLargeTextBlockStyle}"/>
<TextBlock Text="Display" Style="{StaticResource DisplayTextBlockStyle}"/>

Para obter orientação sobre como usar a rampa de tipos do Windows em seu aplicativo, consulte Tipografia em aplicativos do Windows.

Para obter detalhes dos estilos XAML, consulte WinUI no GitHub:

• Legenda TextBlockStyle
• Corpo TextBlockStyle
• Corpo Forte TextBlockStyle

• Legenda TextBlockStyle
• Título TextBlockStyle
• Título Grande TextBlockStyle
• Exibir TextBlockStyle

BaseRichTextBlockStyle

TargetType: RichTextBlock

Fornece as propriedades comuns para todos os outros estilos de contêiner RichTextBlock .

<!-- Usage -->
<RichTextBlock Style="{StaticResource BaseRichTextBlockStyle}">
    <Paragraph>Rich text.</Paragraph>
</RichTextBlock>

<!-- Style definition -->
<Style x:Key="BaseRichTextBlockStyle" TargetType="RichTextBlock">
    <Setter Property="FontFamily" Value="Segoe UI"/>
    <Setter Property="FontWeight" Value="SemiBold"/>
    <Setter Property="FontSize" Value="14"/>
    <Setter Property="TextTrimming" Value="None"/>
    <Setter Property="TextWrapping" Value="Wrap"/>
    <Setter Property="LineStackingStrategy" Value="MaxHeight"/>
    <Setter Property="TextLineBounds" Value="Full"/>
    <Setter Property="OpticalMarginAlignment" Value="TrimSideBearings"/>
</Style>

BodyRichTextBlockStyle

<!-- Usage -->
<RichTextBlock Style="{StaticResource BodyRichTextBlockStyle}">
    <Paragraph>Rich text.</Paragraph>
</RichTextBlock>

<!-- Style definition -->
<Style x:Key="BodyRichTextBlockStyle" TargetType="RichTextBlock" BasedOn="{StaticResource BaseRichTextBlockStyle}">
    <Setter Property="FontWeight" Value="Normal"/>
</Style>

Nota: Os estilos RichTextBlock não têm todos os estilos de rampa de texto que TextBlock tem, principalmente porque o modelo de objeto de documento baseado em bloco para RichTextBlock facilita a definição de atributos nos elementos de texto individuais. Além disso, definir TextBlock.Text usando a propriedade de conteúdo XAML introduz uma situação em que não há nenhum elemento de texto para estilizar e, portanto, você teria que estilizar o contêiner. Isso não é um problema para RichTextBlock porque seu conteúdo de texto sempre precisa estar em elementos de texto específicos, como Parágrafo, que é onde você pode aplicar estilos XAML para cabeçalho de página, subcabeçalho de página e definições de rampa de texto semelhantes.

Estilos nomeados diversos

Há um conjunto adicional de definições de Estilo com chave que você pode aplicar ao estilo de um Button de forma diferente do estilo implícito padrão.

NavigationBackButtonNormalStyle

TargetType: Botão

Este estilo fornece um modelo completo para um botão que pode ser o botão de navegação voltar para um aplicativo de navegação. As dimensões padrão são 40 x 40 pixels. Para personalizar o estilo, você pode definir explicitamente as propriedades Height, Width, FontSize, e outras propriedades em seu Button ou criar um estilo derivado usando BasedOn.

Aqui está um botão com o recurso NavigationBackButtonNormalStyle aplicado a ele.

<Button Style="{StaticResource NavigationBackButtonNormalStyle}" />

Tem a seguinte aparência:

NavegaçãoBackButtonSmallStyle

TargetType: Botão

Este estilo fornece um modelo completo para um botão que pode ser o botão de navegação voltar para um aplicativo de navegação. É semelhante ao NavigationBackButtonNormalStyle, mas suas dimensões são de 30 x 30 pixels.

Aqui está um botão com o recurso NavigationBackButtonSmallStyle aplicado a ele.

<Button Style="{StaticResource NavigationBackButtonSmallStyle}" />

Solução de problemas de recursos temáticos

Se você não seguir as diretrizes para usar recursos de tema, poderá ver um comportamento inesperado relacionado a temas em seu aplicativo.

Por exemplo, quando você abre um submenu com tema claro, partes do seu aplicativo com tema escuro também mudam como se estivessem no tema claro. Ou se você navegar para uma página com tema claro e, em seguida, navegar de volta, a página original com tema escuro (ou partes dela) agora parece estar no tema claro.

Normalmente, esses tipos de problemas ocorrem quando você fornece um tema "Padrão" e um tema "HighContrast" para oferecer suporte a cenários de alto contraste e, em seguida, usa temas "Claro" e "Escuro" em diferentes partes do seu aplicativo.

Por exemplo, considere esta definição de dicionário de temas:

<!-- DO NOT USE. THIS XAML DEMONSTRATES AN ERROR. -->
<ResourceDictionary>
  <ResourceDictionary.ThemeDictionaries>
    <ResourceDictionary x:Key="Default">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource ControlFillColorDefault}"/>
    </ResourceDictionary>
    <ResourceDictionary x:Key="HighContrast">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource SystemColorButtonFaceColor}"/>
    </ResourceDictionary>
  </ResourceDictionary.ThemeDictionaries>
</ResourceDictionary>

Intuitivamente, isso parece correto. Você deseja alterar a cor apontada por myBrush quando em alto contraste, mas quando não em alto contraste, você confia na extensão de marcação {ThemeResource} para garantir que myBrush aponta para a cor certa para o seu tema. Se seu aplicativo nunca tiver FrameworkElement.RequestedTheme definido em elementos dentro de sua árvore visual, isso normalmente funcionará conforme o esperado. No entanto, você tem problemas em seu aplicativo assim que começa a redefinir o tema de diferentes partes da sua árvore visual.

O problema ocorre porque os pincéis são recursos compartilhados, ao contrário da maioria dos outros tipos de XAML. Se você tiver 2 elementos em subárvores XAML com temas diferentes que fazem referência ao mesmo recurso de pincel, à medida que a estrutura percorre cada subárvore para atualizar suas expressões de extensão de marcação {ThemeResource} , as alterações no recurso de pincel compartilhado são refletidas na outra subárvore, o que não é o resultado pretendido.

Para corrigir isso, substitua o dicionário "Padrão" por dicionários de temas separados para temas "Light" e "Dark", além de "HighContrast":

<!-- DO NOT USE. THIS XAML DEMONSTRATES AN ERROR. -->
<ResourceDictionary>
  <ResourceDictionary.ThemeDictionaries>
    <ResourceDictionary x:Key="Light">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource ControlFillColorDefault}"/>
    </ResourceDictionary>
    <ResourceDictionary x:Key="Dark">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource ControlFillColorDefault}"/>
    </ResourceDictionary>
    <ResourceDictionary x:Key="HighContrast">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource SystemColorButtonFaceColor}"/>
    </ResourceDictionary>
  </ResourceDictionary.ThemeDictionaries>
</ResourceDictionary>

No entanto, ainda ocorrem problemas se algum desses recursos for referenciado em propriedades herdadas, como Foreground. Seu modelo de controle personalizado pode especificar a cor de primeiro plano de um elemento usando a extensão de marcação {ThemeResource}, mas quando a estrutura propaga o valor herdado para elementos filho, ela fornece uma referência direta ao recurso que foi resolvido pela expressão de extensão de marcação {ThemeResource}. Isso causa problemas quando a estrutura processa alterações de tema à medida que percorre a árvore visual do controle. Ele reavalia a expressão de extensão de marcação {ThemeResource} para obter um novo recurso de pincel, mas ainda não propaga essa referência para os filhos do seu controle; Isso acontece mais tarde, como durante a próxima aprovação da medida.

Como resultado, depois de percorrer a árvore visual de controle em resposta a uma alteração de tema, a estrutura orienta as crianças e atualiza todas as expressões de extensão de marcação {ThemeResource} definidas nelas ou em objetos definidos em suas propriedades. É aqui que o problema ocorre; a estrutura percorre o recurso de pincel e, como especifica sua cor usando uma extensão de marcação {ThemeResource}, ela é reavaliada.

Neste ponto, a estrutura parece ter poluído seu dicionário de temas porque agora tem um recurso de um dicionário que tem seu conjunto de cores de outro dicionário.

Para corrigir esse problema, use a extensão de marcação {StaticResource} em vez da extensão de marcação {ThemeResource}. Com as diretrizes aplicadas, os dicionários temáticos ficam assim:

<ResourceDictionary>
  <ResourceDictionary.ThemeDictionaries>
    <ResourceDictionary x:Key="Light">
      <SolidColorBrush x:Key="myBrush" Color="{StaticResource ControlFillColorDefault}"/>
    </ResourceDictionary>
    <ResourceDictionary x:Key="Dark">
      <SolidColorBrush x:Key="myBrush" Color="{StaticResource ControlFillColorDefault}"/>
    </ResourceDictionary>
    <ResourceDictionary x:Key="HighContrast">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource SystemColorButtonFaceColor}"/>
    </ResourceDictionary>
  </ResourceDictionary.ThemeDictionaries>
</ResourceDictionary>

Observe que a extensão de marcação {ThemeResource} ainda é usada no dicionário "HighContrast" em vez da extensão de marcação {StaticResource}. Esta situação é abrangida pela exceção prevista anteriormente nas orientações. A maioria dos valores de pincel usados para o tema "HighContrast" está usando opções de cores que são controladas globalmente pelo sistema, mas expostas ao XAML como um recurso especialmente nomeado (aqueles prefixados com 'SystemColor' no nome). O sistema permite que o usuário defina as cores específicas que devem ser usadas para suas configurações de tema de contraste através da Central de Facilidade de Acesso. Essas opções de cores são aplicadas aos recursos especialmente nomeados. A estrutura XAML usa o mesmo evento de tema alterado para também atualizar esses pincéis quando detetar que eles foram alterados no nível do sistema. É por isso que a extensão de marcação {ThemeResource} é usada aqui.