Extensão de marcação {ThemeResource}

Fornece um valor para qualquer atributo XAML avaliando uma referência a um recurso, com lógica de sistema adicional que recupera recursos diferentes dependendo do tema ativo no momento. Semelhante à extensão de marcação {StaticResource}, os recursos são definidos em um ResourceDictionary, e um uso ThemeResource faz referência à chave desse recurso no ResourceDictionary.

Uso de atributos XAML

<object property="{ThemeResource key}" .../>

Valores XAML

Observações

Um ThemeResource é uma técnica para obter valores para um atributo XAML que são definidos em outro lugar em um dicionário de recursos XAML. A extensão de marcação serve a mesma finalidade básica que a extensão de marcação {StaticResource}. A diferença no comportamento versus a extensão de marcação {StaticResource} é que uma referência ThemeResource pode usar dinamicamente dicionários diferentes como o local de pesquisa principal, dependendo de qual tema está sendo usado atualmente pelo sistema.

Quando o aplicativo é iniciado pela primeira vez, qualquer referência de recurso feita por uma referência ThemeResource é avaliada com base no tema em uso na inicialização. Mas se o usuário alterar posteriormente o tema ativo em tempo de execução, o sistema reavaliará cada referência ThemeResource , recuperará um recurso específico do tema que pode ser diferente e exibirá novamente o aplicativo com novos valores de recurso em todos os locais apropriados na árvore visual. Um StaticResource é determinado no momento de carregamento do XAML/início da aplicação e não será reavaliado durante a execução. (Existem outras técnicas, como estados visuais, que recarregam XAML dinamicamente, mas essas técnicas operam em um nível mais alto do que a avaliação básica de recursos habilitada pela extensão de marcação {StaticResource}).

ThemeResource usa um argumento, que especifica a chave para o recurso solicitado. Uma chave de recurso é sempre uma cadeia de caracteres no XAML do Tempo de Execução do Windows. Para saber mais sobre como a chave de recurso é especificada inicialmente, veja atributo x:Key.

Para saber mais sobre como definir recursos e usar corretamente um ResourceDictionary, incluindo código de exemplo, veja ResourceDictionary e referências de recursos XAML.

Importante Assim como StaticResource, um ThemeResource não deve tentar fazer uma referência direta a um recurso definido lexicamente ainda mais dentro do arquivo XAML. A tentativa de fazê-lo não é suportada. Mesmo que a referência avançada não falhe, tentar fazer um acarreta uma penalização de desempenho. Para obter melhores resultados, ajuste a composição dos dicionários de recursos para que as referências diretas sejam evitadas.

A tentativa de especificar um ThemeResource para uma chave que não pode ser resolvida gera uma exceção de análise XAML em tempo de execução. As ferramentas de design também podem oferecer avisos ou erros.

Na implementação do processador XAML do Tempo de Execução do Windows, não há representação de classe de suporte para ThemeResource. O equivalente mais próximo no código é usar a API de coleção de um ResourceDictionary, por exemplo, chamando Contains ou *TryGetValue.

ThemeResource é uma extensão de marcação. As extensões de marcação geralmente são implementadas quando há a necessidade de fugir de valores de atributos diferentes de valores literais ou nomes de funções manipuladoras, e a necessidade é mais abrangente do que apenas colocar conversores de tipos em determinados tipos ou propriedades. Todas as extensões de marcação em XAML usam os caracteres "{" e "}" em sua sintaxe de atributo, que é a convenção pela qual um processador XAML reconhece que uma extensão de marcação deve processar o atributo.

Quando e como usar {ThemeResource} em vez de {StaticResource}

As regras pelas quais um ThemeResource é resolvido para um item num dicionário de recursos são geralmente as mesmas que um StaticResource. Uma pesquisa ThemeResource pode se estender para os arquivos ResourceDictionary que são referenciados em uma coleção ThemeDictionaries , mas um StaticResource também pode fazer isso. A diferença é que um ThemeResource pode reavaliar em tempo de execução e um StaticResource não.

O conjunto de chaves em cada dicionário de temas deve fornecer o mesmo conjunto de recursos chaveados, independentemente do tema ativo. Se um determinado recurso com chave existir no dicionário de tema HighContrast , outro recurso com esse nome também deverá existir em Light e Default. Se isso não for verdade, a pesquisa de recursos poderá falhar quando o utilizador mudar de tema e o seu aplicativo não terá a aparência correta. É possível, no entanto, que um dicionário de temas possa conter recursos chaveados que são referenciados apenas a partir do mesmo escopo para fornecer subvalores; estes não precisam ser equivalentes em todos os temas.

Em geral, você deve colocar recursos em dicionários de temas e fazer referências a esses recursos usando ThemeResource somente quando esses valores podem mudar entre temas ou são suportados por valores que mudam. Isto é apropriado para estes tipos de recursos:

• Pincéis, em particular cores para SolidColorBrush. Eles compõem cerca de 80% dos usos de ThemeResource nos modelos de controle XAML padrão (generic.xaml).
• Valores de píxel para bordas, deslocamentos, margens, preenchimento e afins.
• Propriedades de fonte, como FontFamily ou FontSize.
• Modelos completos para um número limitado de controles que geralmente são estilizados pelo sistema e usados para apresentação dinâmica, como GridViewItem e ListViewItem.
• Estilos de exibição de texto (geralmente para alterar a cor da fonte, o plano de fundo e, possivelmente, o tamanho).

O Tempo de Execução do Windows fornece um conjunto de recursos que se destinam especificamente a ser referenciados por ThemeResource. Todos eles são listados como parte do arquivo XAML themeresources.xaml, que está disponível na pasta include/winrt/xaml/design como parte do Windows Software Development Kit (SDK). Para obter documentação sobre os pincéis de tema e estilos adicionais definidos em themeresources.xaml, consulte Recursos de tema XAML. Os pincéis são documentados em uma tabela que informa qual o valor de cor que cada pincel tem para cada um dos três temas ativos possíveis.

As definições XAML de estados visuais em um modelo de controle devem usar referências ThemeResource sempre que houver um recurso subjacente que possa ser alterado devido a uma alteração de tema. Normalmente, uma alteração no tema do sistema também não causa uma alteração de estado visual. Os recursos precisam usar referências ThemeResource neste caso para que os valores possam ser reavaliados para o estado visual ainda ativo. Por exemplo, se você tiver um estado visual que altera a cor de um pincel de uma parte específica da interface do usuário e uma de suas propriedades, e essa cor do pincel for diferente por tema, você deverá usar uma referência ThemeResource para fornecer o valor dessa propriedade no modelo padrão e também qualquer modificação de estado visual para esse modelo padrão.

Os usos de ThemeResource podem ser vistos em uma série de valores dependentes. Por exemplo, um valor Color usado por um SolidColorBrush que também é um recurso com chave pode usar uma referência ThemeResource . Mas qualquer propriedade da interface do usuário que use o recurso SolidColorBrush com chave também usaria uma referência ThemeResource , de modo que seja especificamente cada propriedade do tipo Pincel que está permitindo uma alteração de valor dinâmico quando o tema muda.

Observação{ThemeResource} e a avaliação de recursos em tempo de execução na alternância de tema é suportada no XAML do Windows 8.1, mas não é suportada no XAML para aplicativos destinados ao Windows 8.

Recursos do sistema

Alguns recursos temáticos fazem referência a valores de recursos do sistema como um subvalor subjacente. Um recurso do sistema é um valor de recurso especial que não é encontrado em nenhum dicionário de recursos XAML. Esses valores dependem do comportamento no suporte a XAML do Windows Runtime para encaminhar valores do sistema em si e representá-los em um formato que um recurso XAML possa referenciar. Por exemplo, há um recurso do sistema chamado "SystemColorButtonFaceColor" que representa uma cor RGB. Essa cor vem dos aspetos de cores e temas do sistema que não são apenas específicos do Windows Runtime e das aplicações Windows Runtime.

Os recursos do sistema geralmente são os valores subjacentes para um tema de alto contraste. O usuário controla as opções de cores para seu tema de alto contraste e faz essas escolhas usando recursos do sistema que também não são específicos dos aplicativos do Tempo de Execução do Windows. Ao fazer referência aos recursos do sistema como referências ThemeResource , o comportamento padrão dos temas de alto contraste para aplicativos do Tempo de Execução do Windows pode usar esses valores específicos do tema que são controlados pelo usuário e expostos pelo sistema. Além disso, as referências agora são marcadas para reavaliação se o sistema detetar uma alteração de tema em tempo de execução.

Um exemplo de uso {ThemeResource}

Aqui estão alguns exemplos de XAML retirados dos arquivos generic.xaml e themeresources.xaml padrão para ilustrar como usar ThemeResource. Examinaremos apenas um modelo (o botão padrão) e como duas propriedades são declaradas (plano de fundo e primeiro plano) para responder às alterações de tema.

    <!-- Default style for Windows.UI.Xaml.Controls.Button -->
    <Style TargetType="Button">
        <Setter Property="Background" Value="{ThemeResource ButtonBackgroundThemeBrush}" />
        <Setter Property="Foreground" Value="{ThemeResource ButtonForegroundThemeBrush}"/>
...

Aqui, as propriedades usam um valor Brush e a referência aos recursos SolidColorBrush é nomeada ButtonBackgroundThemeBrush e ButtonForegroundThemeBrush feita usando ThemeResource.

Essas mesmas propriedades também são ajustadas por alguns dos estados visuais de um Button. Notavelmente, a cor do plano de fundo muda quando um botão é clicado. Aqui também, as animações Plano de fundo e Primeiro plano no storyboard de estado visual usam objetos DiscreteObjectKeyFrame e referências a pincéis com ThemeResource como o valor do quadro-chave.

<VisualState x:Name="Pressed">
  <Storyboard>
    <ObjectAnimationUsingKeyFrames Storyboard.TargetName="Border"
        Storyboard.TargetProperty="Background">
      <DiscreteObjectKeyFrame KeyTime="0" Value="{ThemeResource ButtonPressedBackgroundThemeBrush}" />
    </ObjectAnimationUsingKeyFrames>
    <ObjectAnimationUsingKeyFrames Storyboard.TargetName="ContentPresenter"
         Storyboard.TargetProperty="Foreground">
       <DiscreteObjectKeyFrame KeyTime="0" Value="{ThemeResource ButtonPressedForegroundThemeBrush}" />
    </ObjectAnimationUsingKeyFrames>
  </Storyboard>
</VisualState>

Cada um desses pincéis é definido antes em generic.xaml: eles tinham que ser definidos antes de serem usados por qualquer modelo para evitar referências antecipadas XAML. Aqui estão essas definições, para o dicionário de temas "Padrão".

    <ResourceDictionary.ThemeDictionaries>
        <ResourceDictionary x:Key="Default">
...
            <SolidColorBrush x:Key="ButtonBackgroundThemeBrush" Color="Transparent" />
            <SolidColorBrush x:Key="ButtonForegroundThemeBrush" Color="#FFFFFFFF" />
...
            <SolidColorBrush x:Key="ButtonPressedBackgroundThemeBrush" Color="#FFFFFFFF" />
            <SolidColorBrush x:Key="ButtonPressedForegroundThemeBrush" Color="#FF000000" />
...

Em seguida, cada um dos outros dicionários temáticos também tem estes pincéis definidos, por exemplo:

        <ResourceDictionary x:Key="HighContrast">
            <!-- High Contrast theme resources -->
...
            <SolidColorBrush x:Key="ButtonBackgroundThemeBrush" Color="{ThemeResource SystemColorButtonFaceColor}" />
            <SolidColorBrush x:Key="ButtonForegroundThemeBrush" Color="{ThemeResource SystemColorButtonTextColor}" />

...
            <SolidColorBrush x:Key="ButtonPressedBackgroundThemeBrush" Color="{ThemeResource SystemColorButtonTextColor}" />
            <SolidColorBrush x:Key="ButtonPressedForegroundThemeBrush" Color="{ThemeResource SystemColorButtonFaceColor}" />

Aqui, o valor Color é outra referência ThemeResource a um recurso do sistema. Se você fizer referência a um recurso do sistema e quiser que ele seja alterado em resposta a uma alteração de tema, use ThemeResource para fazer a referência.

Suporte para ferramentas de design para a extensão de marcação {ThemeResource}

O Microsoft Visual Studio pode incluir possíveis valores de chave nos menus suspensos do Microsoft IntelliSense quando se utiliza a extensão de marcação {ThemeResource} numa página XAML. Por exemplo, assim que você digita "{ThemeResource", qualquer uma das chaves de recurso dos recursos de tema XAML é exibida.

Quando uma chave de recurso existe como parte de qualquer uso do {ThemeResource}, a funcionalidade Ir para Definição (F12) pode resolver esse recurso e mostrar o generic.xaml durante o tempo de design, onde o recurso de tema é definido. Como os recursos do tema são definidos mais de uma vez (por tema), Ir para Definição leva você à primeira definição encontrada no arquivo, que é a definição para Padrão. Se você quiser as outras definições, você pode procurar o nome da chave dentro do arquivo e encontrar as definições dos outros temas.

Tópicos relacionados

• Referências de recursos do ResourceDictionary e XAML
• recursos de tema XAML
• ResourceDictionary
• x:Atributo chave