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 do atributo XAML

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

Valores XAML

Observações

Um ThemeResource é uma técnica para obter valores para um atributo XAML definido em outro lugar em um dicionário de recursos XAML. A extensão de marcação serve à 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 no momento 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. No entanto, 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 redimensivará o aplicativo com novos valores de recurso em todos os locais apropriados na árvore visual. Um StaticResource é determinado no momento de carregamento do XAML ou na inicialização do aplicativo e não será reavaliado em tempo de execução. (Há outras técnicas, como estados visuais, que recarregam XAML dinamicamente, mas essas técnicas operam em um nível mais alto que a avaliação básica de recursos habilitada pela extensão de marcação {StaticResource}).

ThemeResource usa um argumento, que especifica a chave do recurso solicitado. Uma chave de recurso é sempre uma cadeia de caracteres no XAML do Windows Runtime. Para obter mais informações sobre como a chave de recurso é especificada inicialmente, consulte o atributo x:Key.

Para obter mais informações sobre como definir recursos e usar corretamente um ResourceDictionary, incluindo o código de exemplo, consulte referências de recursos ResourceDictionary e XAML.

Importante Assim como acontece com StaticResource, um ThemeResource não deve tentar fazer uma referência de encaminhamento a um recurso definido lexicamente mais adiante no arquivo XAML. Não há suporte para a tentativa de fazer isso. Mesmo que a referência de avanço não falhe, tentar fazer uma delas traz uma penalidade de desempenho. Para obter melhores resultados, ajuste a composição dos dicionários de recursos para que as referências futuras 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 Windows Runtime, não há representação de classe de backup 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 normalmente são implementadas quando há um requisito para escapar de valores de atributo que não sejam valores literais ou nomes de manipulador, e o requisito é mais global do que apenas colocar conversores de tipo em determinados tipos ou propriedades. Todas as extensões de marcação no 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 se resolve em um item em um dicionário de recursos geralmente são as mesmas do 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 ser reavaliado em tempo de execução e um StaticResource não pode.

O conjunto de chaves em cada dicionário de temas deve fornecer o mesmo conjunto de recursos chaveados, independentemente de qual tema esteja ativo. Se um determinado recurso com chave existir no dicionário de temas HighContrast , outro recurso com esse nome também deverá existir em Luz e Padrão. Se isso não for verdade, a pesquisa de recursos poderá falhar quando o usuário mudar de tema e seu aplicativo poderá não ficar com a aparência correta. É possível, porém, que um dicionário de temas possa conter recursos chaveados que só são referenciados dentro do mesmo escopo para fornecer sub-valores; elas 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 ser alterados entre temas ou têm suporte por valores que são alterados. Isso é apropriado para esses tipos de recursos:

• Pincéis, em cores específicas para SolidColorBrush. Elas compõem cerca de 80% dos usos themeResource nos modelos de controle XAML padrão (generic.xaml).
• Valores de pixel para bordas, deslocamentos, margem e preenchimento e assim por diante.
• Propriedades de fonte, como FontFamily ou FontSize.
• Conclua modelos para um número limitado de controles que geralmente têm estilo de sistema e são 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 o tamanho possivelmente).

O Windows Runtime fornece um conjunto de recursos que se destinam especificamente a serem referenciados por ThemeResource. Todos eles estão listados como parte do arquivo XAML themeresources.xaml, que está disponível na pasta include/winrt/xaml/design como parte do SDK (Kit de Desenvolvimento de Software do Windows). Para obter documentação sobre os pincéis de tema e estilos adicionais definidos em themeresources.xaml, consulte os recursos de tema XAML. Os pincéis são documentados em uma tabela que informa qual valor de cor 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 mudar devido a uma alteração de tema. Uma alteração de tema do sistema normalmente não resultará em uma alteração de estado visual. Os recursos precisam usar referências ThemeResource nesse caso para que os valores possam ser reavaliados para o estado visual ainda ativo. Por exemplo, se você tiver um estado visual que altera uma cor de pincel de uma determinada parte da interface do usuário e uma de suas propriedades, e essa cor de 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 nesse 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 todas as propriedades de interface do usuário que usam o recurso SolidColorBrush com chave também usariam uma referência ThemeResource , de modo que seja especificamente cada propriedade do tipo Brush que está habilitando uma alteração de valor dinâmico quando o tema é alterado.

Nota{ThemeResource} há suporte para a avaliação de recursos em tempo de execução na alternância de tema no Windows 8.1 XAML, mas não há suporte no XAML para aplicativos direcionados ao Windows 8.

Recursos do sistema

Alguns recursos de tema fazem referência aos valores de recurso do sistema como um sub-valor 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 ao XAML do Windows Runtime para encaminhar valores do próprio sistema e representá-los em um formulário que um recurso XAML pode referenciar. Por exemplo, há um recurso do sistema chamado "SystemColorButtonFaceColor" que representa uma cor RGB. Essa cor vem de aspectos das cores e temas do sistema que não se limitam apenas ao Windows Runtime e aos aplicativos do 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 o usuário faz essas escolhas usando recursos do sistema que também não são específicos para aplicativos do Windows Runtime. Ao referenciar os recursos do sistema como referências themeResource , o comportamento padrão dos temas de alto contraste para aplicativos do Windows Runtime 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 detectar uma alteração de tema em tempo de execução.

Um exemplo de uso de {ThemeResource}

Veja alguns exemplos de XAML obtidos 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 a recursos SolidColorBrush nomeados ButtonBackgroundThemeBrush e ButtonForegroundThemeBrush são feitas usando ThemeResource.

Essas mesmas propriedades também são ajustadas por alguns dos estados visuais de um Botão. Notavelmente, a cor da tela de fundo muda quando um botão é clicado. Aqui também, as animações Background e Foreground 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 anteriormente em generic.xaml: eles tinham que ser definidos antes que qualquer modelo os usasse para evitar referências anteriores 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 de temas também tem esses 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 de Cor é 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 de ferramentas de tempo de design para a extensão de marcação {ThemeResource}

O Microsoft Visual Studio pode incluir possíveis valores de chave nas listas suspensas do Microsoft IntelliSense quando você usa a extensão de marcação {ThemeResource} em uma página XAML. Por exemplo, assim que você digitar "{ThemeResource", qualquer uma das chaves de recurso dos recursos de tema XAML será exibida.

Depois que uma chave de recurso existir como parte de qualquer uso de {ThemeResource}, a função Ir para Definição (F12) pode resolver esse recurso e mostrar o generic.xaml durante o tempo de design, onde o recurso do tema é definido. Como os recursos de 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 de Padrão. Se você quiser as outras definições, poderá pesquisar o nome da chave dentro do arquivo e encontrar as definições dos outros temas.

Tópicos relacionados

• ResourceDictionary e referências de recursos do XAML
• Recursos de temas XAML
• ResourceDictionary
• Atributo x:Key