Extensão de marcação {ThemeResource}{ThemeResource} markup extension

Fornece um valor para qualquer atributo XAML avaliando uma referência a um recurso, com lógica do sistema adicional que recupera diferentes recursos, dependendo do tema ativo no momento.Provides a value for any XAML attribute by evaluating a reference to a resource, with additional system logic that retrieves different resources depending on the currently active theme. Assim como a extensão de marcação {StaticResource}, os recursos são definidos em um ResourceDictionary e o uso de ThemeResource faz referência à chave desse recurso no ResourceDictionary.Similar to {StaticResource} markup extension, resources are defined in a ResourceDictionary, and a ThemeResource usage references the key of that resource in the ResourceDictionary.

Uso do atributo XAMLXAML attribute usage

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

Valores XAMLXAML values

TermoTerm DescriçãoDescription
chavekey A chave para o recurso solicitado.The key for the requested resource. Essa chave é inicialmente atribuída pelo ResourceDictionary.This key is initially assigned by the ResourceDictionary. Uma chave de recurso pode ser qualquer cadeia de caracteres definida na gramática de XamlName.A resource key can be any string defined in the XamlName Grammar.

ComentáriosRemarks

A ThemeResource é uma técnica para obtenção de valores referentes a um atributo XAML definidos em outro lugar em um dicionário de recursos XAML.A ThemeResource is a technique for obtaining values for a XAML attribute that are defined elsewhere in a XAML resource dictionary. Essa extensão de marcação tem a mesma finalidade básica que a extensão de marcação StaticResource.The markup extension serves the same basic purpose as the {StaticResource} markup extension. A diferença de comportamento em relação à extensão de marcação {StaticResource} é que uma referência ThemeResource pode usar dinamicamente diferentes dicionários como o local de pesquisa principal, dependendo do tema atualmente utilizado pelo sistema.The difference in behavior versus {StaticResource} markup extension is that a ThemeResource reference can dynamically use different dictionaries as the primary lookup location, depending on which theme is currently being used by the system.

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 durante a inicialização.When the app first starts, any resource reference made by a ThemeResource reference is evaluated based on the theme in use at startup. Mas se o usuário mudar posteriormente o tema ativo no 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 os novos valores de recurso em todos os locais apropriados da árvore visual.But if the user subsequently changes the active theme at run-time, the system will re-evaluate every ThemeResource reference, retrieve a theme-specific resource that may be different, and redisplay the app with new resource values in all appropriate places in the visual tree. Uma StaticResource é determinada no tempo de carregamento do XAML/inicialização do aplicativo e não será reavaliada no tempo de execução.A StaticResource is determined at XAML load time / app startup and won't be re-evaluated at run-time. (Há outras técnicas como estados visuais que recarregam o XAML dinamicamente, mas essas técnicas operam em um nível mais elevado do que a avaliação de recurso básica ativada pela extensão de marcação {StaticResource}).(There are other techniques such as visual states that reload XAML dynamically, but those techniques operate at a higher level that the basic resource evaluation enabled by {StaticResource} markup extension).

ThemeResource obtém um argumento, que especifica a chave para o recurso solicitado.ThemeResource takes one argument, which specifies the key for the requested resource. Uma chave de recurso sempre é uma cadeia de caracteres no XAML de Tempo de Execução do Windows.A resource key is always a string in Windows Runtime XAML. Para obter mais informações sobre como a chave de recurso é especificada inicialmente, consulte atributo x:Key.For more info on how the resource key is initially specified, see x:Key attribute.

Para obter mais informações sobre como definir recursos e como usar adequadamente um ResourceDictionary, incluindo o exemplo de código, consulte Referências aos recursos ResourceDictionary e XAML.For more info on how to define resources and properly use a ResourceDictionary, including sample code, see ResourceDictionary and XAML resource references.

Importante Assim como no caso de StaticResource, um ThemeResource não deve tentar fazer uma referência posterior a um recurso que é definido lexicalmente mais fundo no arquivo XAML.Important As with StaticResource, a ThemeResource must not attempt to make a forward reference to a resource that is defined lexically further within the XAML file. Não é possível fazer isso.Attempting to do so is not supported. Mesmo se a referência de encaminhamento não falhar, tentar fazê-la acarreta uma penalidade de desempenho.Even if the forward reference doesn't fail, trying to make one carries a performance penalty. Para obter melhores resultados, ajuste a composição dos seus dicionários de recursos de maneira que seja possível evitar referências de encaminhamento.For best results, adjust the composition of your resource dictionaries so that forward references are avoided.

Tentar especificar um ThemeResource para uma chave incapaz de resolver gera uma exceção de análise de XAML em tempo de execução.Attempting to specify a ThemeResource to a key that cannot resolve throws a XAML parse exception at run time. As ferramentas de design também podem apresentar avisos ou erros.Design tools may also offer warnings or errors.

Na implementação do processador XAML do Windows Runtime, não há uma representação de classe de suporte para a funcionalidade ThemeResource.In the Windows Runtime XAML processor implementation, there is no backing class representation for ThemeResource. O equivalente mais próximo em código é usar a API de coleção de um ResourceDictionary, chamando, por exemplo, Contains ou TryGetValue.The closest equivalent in code is to use the collection API of a ResourceDictionary, for example calling Contains or TryGetValue.

ThemeResource é uma extensão de marcação.ThemeResource is a markup extension. Extensões de marcação são tipicamente implementadas quando existe um requisito que permite que valores de atributo sejam diferentes de valores literais ou nomes de manipuladores, e o requisito é mais global do que simplesmente colocar conversores de tipo em certos tipos ou propriedades.Markup extensions are typically implemented when there is a requirement to escape attribute values to be other than literal values or handler names, and the requirement is more global than just putting type converters on certain types or properties. Todas as extensões de marcação em XAML usam os caracteres "{" e "}" na sintaxe de atributo, sendo esta a convenção pela qual um processador XAML reconhece que uma extensão de marcação deve processar o atributo.All markup extensions in XAML use the "{" and "}" characters in their attribute syntax, which is the convention by which a XAML processor recognizes that a markup extension must process the attribute.

Quando e como usar {ThemeResource} em vez de {StaticResource}When and how to use {ThemeResource} rather than {StaticResource}

As regras pelas quais ThemeResource é resolvido para um item em um dicionário de recursos costumam ser as mesmas de StaticResource.The rules by which a ThemeResource resolves to an item in a resource dictionary are generally the same as StaticResource. Uma pesquisa de ThemeResource pode ser estendida para os arquivos do ResourceDictionary que são referenciados em uma coleção de ThemeDictionaries, mas um StaticResource também pode fazer isso.A ThemeResource lookup can extend into the ResourceDictionary files that are referenced in a ThemeDictionaries collection, but a StaticResource can do that also. A diferença é que um ThemeResource pode ser reavaliado no tempo de execução e um StaticResource não.The difference is that a ThemeResource can re-evaluate at run-time and a StaticResource can't.

O conjunto de chaves em cada dicionário de temas deve fornecer o mesmo conjunto de recursos de chave, independentemente do tema ativo.The set of keys in each theme dictionary should provide the same set of keyed resources no matter which theme is active. Se um determinado recurso de chave existir no dicionário de temas HighContrast, outro recurso com esse nome também deverá existir em Light e Default.If a given keyed resource exists in the HighContrast theme dictionary, then another resource with that name should also exist in Light and Default. Se isso não for verdadeiro, a pesquisa de recurso poderá falhar quando o usuário alternar entre os temas e o seu aplicativo não parecerá correto.If that isn't true, resource lookup might fail when the user switches themes and your app won't look right. Entretanto, é possível que um dicionário de temas contenha recursos de chave que sejam referenciados apenas no mesmo escopo para fornecer subvalores; eles não precisam ser equivalentes em todos os temas.It is possible though that a theme dictionary can contain keyed resources that are only referenced from within the same scope to provide sub-values; these don't need to be equivalent in all themes.

Em geral, você deve colocar os recursos nos mesmos dicionários de temas e fazer referências a esses recursos usando ThemeResource somente quando esses valores puderem mudar entre os temas ou forem compatíveis com valores que mudam.In general you should place resources in theme dictionaries and make references to those resources using ThemeResource only when those values can change between themes or are supported by values that change. Isso é apropriado para estes tipos de recurso:This is appropriate for these kinds of resources:

  • Pincéis, em determinadas cores para SolidColorBrush.Brushes, in particular colors for SolidColorBrush. Eles compõem cerca de 80% dos usos de ThemeResource nos modelos de controle XAML padrão (generic.xaml).These make up about 80% of the ThemeResource usages in the default XAML control templates (generic.xaml).
  • Valores de pixel para bordas, deslocamentos, margens e preenchimento, etc.Pixel values for borders, offsets, margin and padding and so on.
  • Propriedades de fonte como FontFamily ou FontSize.Font properties such as FontFamily or FontSize.
  • Modelos completos para um número limitado de controles que costumam ter o estilo do sistema e ser usados para apresentação dinâmica, como GridViewItem e ListViewItem.Complete templates for a limited number of controls that are usually system-styled and used for dynamic presentation, like GridViewItem and ListViewItem.
  • Estilos de exibição de texto (geralmente para mudar a cor da fonte, a tela de fundo e possivelmente o tamanho).Text display styles (usually to change font color, background, and possibly size).

O Windows Runtime fornece um conjunto de recursos especialmente concebido para ser referenciado por ThemeResource.The Windows Runtime provides a set of resources that are specifically intended to be referenced by ThemeResource. Todos esses recursos estão listados como parte do arquivo XAML themeresources.xaml, que está disponível na pasta include/winrt/xaml/design integrante do Software Development Kit do Windows (SDK do Windows).These are all listed as part of the XAML file themeresources.xaml, which is available in the include/winrt/xaml/design folder as part of the Windows Software Development Kit (SDK). Para conhecer a documentação sobre pincéis de temas e estilos adicionais que estão definidos em themeresources.xaml, consulte Recursos de temas XAML.For documentation on the theme brushes and additional styles that are defined in themeresources.xaml, see XAML theme resources. Os pincéis estão documentados em uma tabela que informa o valor de cor de cada pincel em cada um dos três temas ativos possíveis.The brushes are documented in a table that tells you what color value each brush has for each of the three possible active themes.

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.The XAML definitions of visual states in a control template should use ThemeResource references whenever there's an underlying resource that might change because of a theme change. Tipicamente, uma alteração de tema do sistema não causa uma alteração de estado visual.A system theme change won't typically also cause a visual state change. Os recursos precisam usar referências ThemeResource nesse caso, para que os valores possam ser reavaliados para o estado visual ainda ativo.The resources need to use ThemeResource references in this case so that values can be re-evaluated for the still-active visual state. Por exemplo, se você tiver um estado visual que muda a cor de um pincel de uma determinada interface do usuário e uma de suas propriedades, e a cor desse pincel for diferente em cada 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.For example, if you have a visual state that changes a brush color of a particular UI part and one of its properties, and that brush color is different per-theme, you should use a ThemeResource reference for providing that property's value in the default template and also any visual state modification to that default template.

O uso de ThemeResource pode ser visto em uma série de valores dependentes.ThemeResource usages might be seen in a series of dependent values. Por exemplo, um valor Color usado por um SolidColorBrush que também é um recurso de chave pode usar uma referência ThemeResource.For example, a Color value used by a SolidColorBrush that is also a keyed resource might use a ThemeResource reference. Mas quaisquer propriedades de interface do usuário que usem o recurso de chave SolidColorBrush também deverão usar uma referência ThemeResource, para que cada propriedade de tipo de Brush que esteja ativando um valor dinâmico mude quando o tema mudar.But any UI properties that use the keyed SolidColorBrush resource would also use a ThemeResource reference, so that it's specifically each Brush-type property that's enabling a dynamic value change when the theme changes.

Observação   {ThemeResource} e a avaliação de recursos em tempo de execução na alternância de temas tem suporte em Windows 8.1 XAML, mas sem suporte em XAML para aplicativos direcionados para o Windows 8.Note  {ThemeResource} and run-time resource evaluation on theme switching is supported in Windows 8.1 XAML but not supported in XAML for apps targeting Windows 8.

Recursos do sistemaSystem resources

Alguns recursos do sistema fazem referência a valores de recursos do sistema como um subvalor adjacente.Some theme resources reference system resource values as an underlying sub-value. Um recurso do sistema é um valor de recurso especial que não pode ser encontrado em nenhum dicionário de recursos XAML.A system resource is a special resource value that isn't found in any XAML resource dictionary. Esses valores se baseiam no comportamento de suporte ao XAML do Windows Runtime para encaminhar os valores do próprio sistema e representá-los de uma forma que um recurso XAML possa fazer referência.These values rely on behavior in Windows Runtime XAML support to forward values from the system itself, and represent them in a form that a XAML resource can reference. Por exemplo, há um recurso do sistema denominado "SystemColorButtonFaceColor" que representa uma cor RGB.For example, there is a system resource named "SystemColorButtonFaceColor" that represents an RGB color. Essa cor é proveniente de aspectos de cores e temas do sistema que não são simplesmente específicos do Windows Runtime e de seus respectivos aplicativos.This color comes from the aspects of system colors and themes that aren't just specific to Windows Runtime and Windows Runtime apps.

Os recursos do sistema costumam ser valores subjacentes para um tema em alto contraste.System resources are often the underlying values for a high-contrast theme. O usuário controla as opções de cores do tema em alto contraste e o usuário faz essas escolhas usando recursos do sistema que também não são específicos dos aplicativos do Windows Runtime.The user is in control of the color choices for their high-contrast theme, and the user makes these choices using system features that also aren't specific to Windows Runtime apps. Quando é feita referência aos recursos do sistema como referências ThemeResource, o comportamento padrão dos temas em alto contraste dos aplicativos do Windows Runtime pode usar esses valores específicos do tema que são controlados pelo usuário e apresentados pelo sistema.By referencing the system resources as ThemeResource references, the default behavior of the high-contrast themes for Windows Runtime apps can use these theme-specific values that are controlled by the user and exposed by the system. Além disso, as referências agora são marcadas para reavaliação quando o sistema detecta uma alteração de tema de tempo de execução.Also, the references are now marked for re-evaluation if the system detects a run-time theme change.

Exemplo de uso de {ThemeResource}An example {ThemeResource} usage

Veja a seguir alguns exemplos de XAML extraídos dos arquivos padrão generic.xaml e themeresources.xaml para ilustrar como usar ThemeResource.Here's some example XAML taken from the default generic.xaml and themeresources.xaml files to illustrate how to use ThemeResource. Vamos analisar apenas um modelo (o Button padrão) e como duas propriedades são declaradas (Background e Foreground) para serem responsivas às alterações de temas.We'll look at just one template (the default Button) and how two properties are declared (Background and Foreground) to be responsive to theme changes.

    <!-- 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 assumem um valor Brush e a referência aos recursos SolidColorBrush nomeadas ButtonBackgroundThemeBrush e ButtonForegroundThemeBrush são feitas usando ThemeResource.Here, the properties take a Brush value, and the reference to SolidColorBrush resources named ButtonBackgroundThemeBrush and ButtonForegroundThemeBrush are made using ThemeResource.

Essas mesmas propriedades também são ajustadas por alguns dos estados visuais para um Button.These same properties are also adjusted by some of the visual states for a Button. Notavelmente, a cor da tela de fundo muda quando um botão é clicado.Notably, the background color changes when a button is clicked. Aqui também, as animações de Background e Foreground no storyboard de estados visuais usam objetos DiscreteObjectKeyFrame e referências a pincéis com ThemeResource como o valor chave.Here too, the Background and Foreground animations in the visual state storyboard use DiscreteObjectKeyFrame objects and references to brushes with ThemeResource as the key frame value.

<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 previamente em generic.xaml: eles precisam ser definidos antes de serem utilizados por qualquer modelo, para evitar referências posteriores de XAML.Each of these brushes is defined earlier in generic.xaml: they had to be defined prior to any templates using them to avoid XAML forward references. Aqui estão essas definições, para o dicionário de temas "Padrão".Here's those definitions, for the "Default" theme dictionary.

    <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" />
...

Depois, os pincéis de cada um dos outros dicionários de temas também são definidos, por exemplo:Then each of the other theme dictionaries also has these brushes defined, for example:

        <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.Here the Color value is another ThemeResource reference to a system resource. Se você fizer referência a um recurso do sistema e quiser que ele mude em resposta a uma alteração de tema, você deverá usar ThemeResource para fazer a referência.If you reference a system resource, and you want it to change in response to a theme change, you should use ThemeResource to make the reference.

Comportamento do Windows 8Windows 8 behavior

O Windows 8 não dava suporte à extensão de marcação ThemeResource, ela está disponível a partir do Windows 8.1.Windows 8 did not support the ThemeResource markup extension, it is available starting with Windows 8.1. Além disso, o Windows 8 não dava suporte à alternância dinâmica dos recursos relacionados ao tema de um aplicativo do Windows Runtime.Also, Windows 8 did not support dynamically switching the theme-related resources for a Windows Runtime app. O aplicativo tinha que ser reiniciado para selecionar a alteração de tema dos modelos e estilos XAML.The app had to be restarted in order to pick up the theme change for the XAML templates and styles. Essa não é uma boa experiência de usuário, portanto, os aplicativos devem ser recompilados e visar o Windows 8.1 de forma que possam usar estilos com usos ThemeResource e possam alternar dinamicamente os temas quando o usuário o faz.This isn't a good user experience, so apps are strongly encouraged to recompile and target Windows 8.1 so that they can use styles with ThemeResource usages and can dynamically switch themes when the user does. Os aplicativos que foram compilados para Windows 8, mas estão sendo executados no Windows 8.1, continuam a adotar o comportamento do Windows 8.Apps that were compiled for Windows 8 but running on Windows 8.1 continue to use the Windows 8 behavior.

As ferramentas de tempo de design têm suporte para a extensão de marcação {ThemeResource}Design-time tools support for the {ThemeResource} markup extension

O Microsoft Visual Studio 2013 pode incluir valores-chave possíveis nos menus suspensos do Microsoft IntelliSense quando você usa a extensão de marcação {ThemeResource} em uma página XAML.Microsoft Visual Studio 2013 can include possible key values in the Microsoft IntelliSense dropdowns when you use the {ThemeResource} markup extension in a XAML page. Por exemplo, assim que você digita "{ThemeResource", todas as chaves de recurso dos recursos de tema XAML são exibidas.For example, as soon as you type "{ThemeResource", any of the resource keys from the XAML theme resources are displayed.

Quando uma chave de recurso existe como parte de qualquer uso {ThemeResource}, o recurso Ir para Definição (F12) pode resolver esse recurso e mostrar a você o generic.xaml do tempo de design, em que o recurso do tema é definido.Once a resource key exists as part of any {ThemeResource} usage, the Go To Definition (F12) feature can resolve that resource and show you the generic.xaml for design time, where the theme resource is defined. 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 de Padrão.Because theme resources are defined more than once (per-theme) Go To Definition takes you to the first definition found in the file, which is the definition for Default. Se você desejar obter as outras definições, poderá procurar o nome da chave no arquivo e localizar as definições dos outros temas.If you want the other definitions you can search for the key name within the file and find the other themes' definitions.