ResourceDictionary Classe

Definição

Namespace:

Windows.UI.Xaml

Define um repositório para recursos XAML, como estilos, que seu aplicativo usa. Você define os recursos em XAML e pode recuperá-los em XAML usando a extensão de marcação {StaticResource} e as extensões de marcação {ThemeResource} . Você também pode acessar recursos com código, mas isso é menos comum.

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class ResourceDictionary : DependencyObject, IIterable<IKeyValuePair<IInspectable, IInspectable const&>>, IMap<IInspectable, IInspectable const&>

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public class ResourceDictionary : DependencyObject, IDictionary<object,object>, IEnumerable<KeyValuePair<object,object>>

Public Class ResourceDictionary
Inherits DependencyObject
Implements IDictionary(Of Object, Object), IEnumerable(Of KeyValuePair(Of Object, Object))

<ResourceDictionary>
  oneOrMoreResources
</ResourceDictionary>
- or -
<frameworkElement>
  <frameworkElement.Resources>
    oneOrMoreResources
  </frameworkElement.Resources>
</frameworkElement>

Herança

Object IInspectable DependencyObject ResourceDictionary

Derivado

Windows.UI.Xaml.ColorPaletteResources

Atributos

ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Implementações

IDictionary<Object,Object> IMap<IInspectable,IInspectable> IIterable<IKeyValuePair<K,V>> IEnumerable<KeyValuePair<K,V>> IEnumerable<KeyValuePair<Object,Object>> IIterable<IKeyValuePair<IInspectable,IInspectable>>

Requisitos do Windows

Família de dispositivos	Windows 10 (introduzida na 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (introduzida na v1.0)

Comentários

Um dicionário de recursos é um repositório para recursos XAML, como estilos, que seu aplicativo usa. Você define os recursos em XAML e pode recuperá-los em XAML usando a extensão de marcação {StaticResource} e as extensões de marcação {ThemeResource} . Você também pode acessar recursos com código, mas isso é menos comum. Você pode usar recursos para impor que determinados valores, como cores de pincel ou medidas de pixel, sejam usados consistentemente em todo o aplicativo. Para obter mais informações sobre como usar dicionários de recursos com eficiência, consulte Referências de recursos ResourceDictionary e XAML.

Usos de elementos ResourceDictionary

O tipo ResourceDictionary é usado como o valor de duas propriedades, FrameworkElement.Resources e Application.Resources, que são importantes para a estrutura geral de um aplicativo UWP. Os arquivos XAML obtidos de um modelo de projeto inicial para um aplicativo começarão com valores iniciais para FrameworkElement.Resources e o arquivo app.xaml poderá começar com valores iniciais para Application.Resources. Exatamente quais recursos são definidos lá depende de qual modelo inicial de projeto você está usando.

Este XAML mostra o uso de uma propriedade FrameworkElement.Resources . Nesse caso, FrameworkElement é uma Página. Não há nenhum elemento ResourceDictionary subordinado ao elemento de propriedade Page.Resources, mas sua presença está implícita; para obter mais informações, consulte a seção "Anotações sobre sintaxe XAML" abaixo. O XAML coloca um Estilo no ResourceDictionary com um valor de atributo x:Key de "TextBlockStyle1". Mais abaixo no XAML, a extensão de marcação {StaticResource} faz referência ao Estilo no dicionário de recursos para fornecer um valor para a propriedade Style do elemento TextBlock .

O Estilo , conforme mostrado, não aplica nenhum estilo ao TextBlock, mas você pode adicionar propriedades style no Microsoft Visual Studio. Em seguida, você pode usar o recurso Estilo com a frequência que desejar na página para impor a uniformidade.

Você pode usar o Microsoft Visual Studio para criar dicionários de recursos. Este exemplo foi criado com estas etapas: coloque um TextBlock na superfície de design, clique com o botão direito do mouse, escolha Editar Estilo/Criar Vazio e, em seguida, "Este documento" para definir o novo recurso em Page.Resources.

<Page
    x:Class="ResourceDictionary_example.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:ResourceDictionary_example"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d">
    <Page.Resources>
        <Style x:Key="TextBlockStyle1" TargetType="TextBlock"/>
    </Page.Resources>

    <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
        <TextBlock Style="{StaticResource TextBlockStyle1}" Text="TextBlock"/>
    </Grid>
</Page>

Esse XAML, do arquivo AppPage.xaml do exemplo AtomPub, mostra o uso de uma propriedade Application.Resources . O XAML coloca dois elementos Style no dicionário de recursos, disponibilizando-os em todo o aplicativo.

<Application xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
    x:Class="AtomPub.App"
    RequestedTheme="Light" >
    <Application.Resources>
        <ResourceDictionary>
            <Style x:Key="TitleStyle" TargetType="TextBlock">
                <Setter Property="Foreground" Value="#707070"/>
                <Setter Property="FontFamily" Value="Segoe UI Light"/>
                <Setter Property="FontSize" Value="16"/>
            </Style>
            <Style x:Key="H1Style" TargetType="TextBlock">
                <Setter Property="Foreground" Value="#212121"/>
                <Setter Property="FontFamily" Value="Segoe UI Semilight"/>
                <Setter Property="FontSize" Value="26.667"/>
                <Setter Property="Margin" Value="0,0,0,25"/>
            </Style>
            ...
        </ResourceDictionary>
    </Application.Resources>
</Application> 

Este XAML do arquivo MainPage.xaml usa a extensão de marcação {StaticResource} para acessar os estilos TitleStyle e H1Style :

...
<!-- Header -->
<StackPanel x:Name="Header" Grid.Row="0">
    <StackPanel Orientation="Horizontal">
        ...
        <TextBlock Text="Windows SDK Samples" VerticalAlignment="Bottom" Style="{StaticResource TitleStyle}" TextWrapping="Wrap"/>
    </StackPanel>
    <TextBlock x:Name="FeatureName" Text="Add Feature Name" Style="{StaticResource H1Style}" TextWrapping="Wrap"/>
</StackPanel>
 ...

Você pode fatorar recursos em seu próprio arquivo XAML usando ResourceDictionary como o elemento raiz do arquivo. Em seguida, você pode incluir esses recursos em um dicionário de recursos FrameworkElement.Resources ou Application.Resources . Para fazer isso, use a propriedade ResourceDictionary.MergedDictionaries ou a propriedade ResourceDictionary.ThemeDictionaries do elemento ResourceDictionary.

Esse arquivo, Common/Styles1.xaml, define recursos de estilo usando ResourceDictionary como o elemento raiz:

<ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <Style x:Key="TitleTextStyle" TargetType="TextBlock">
        <Setter Property="FontFamily" Value="Segoe UI Light"/>
        <Setter Property="FontSize" Value="16"/>
    </Style>
    <Style x:Key="HeaderTextStyle" TargetType="TextBlock">
        <Setter Property="FontFamily" Value="Segoe UI Semilight"/>
        <Setter Property="FontSize" Value="26.667"/>
        <Setter Property="Margin" Value="0,0,0,25"/>
    </Style>
    ...
</ResourceDictionary>

Agora suponha que haja outro arquivo, Common/Styles2.xaml que defina recursos de estilo da mesma forma. Este XAML mostra como mesclar os recursos nesses dois arquivos usando a propriedade ResourceDictionary.MergedDictionaries para criar um dicionário de recursos Application.Resources . O XAML também define mais dois recursos de Estilo e os mescla com os recursos dos dois arquivos.

<Application
    .... >
    <Application.Resources>
        <ResourceDictionary>
            <Style x:Key="ErrorStyle" TargetType="TextBlock">
                <Setter Property="Foreground" Value="DarkRed"/>
                <Setter Property="FontFamily" Value="Segoe UI Semilight"/>
                <Setter Property="FontSize" Value="15"/>
            </Style>
            <Style x:Key="StatusStyle" TargetType="TextBlock">
                <Setter Property="Foreground" Value="Black"/>
                <Setter Property="FontFamily" Value="Segoe UI Semilight"/>
                <Setter Property="FontSize" Value="15"/>
            </Style>
            <ResourceDictionary.MergedDictionaries>
                <!-- 
                    Styles that define common aspects of the platform look and feel
                 -->
                <ResourceDictionary Source="Common/Styles1.xaml"/>
                <ResourceDictionary Source="Common/Styles2.xaml"/>
            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </Application.Resources>
</Application>

Para obter informações sobre como os recursos de dicionário mesclados são resolvidos, consulte a seção "Dicionários de recursos mesclados" das referências de recursos ResourceDictionary e XAML.

A propriedade x:Key

Em XAML, as chaves para ResourceDictionaryitems são declaradas definindo o atributo x:Keyem elementos que representam os recursos XAML. Normalmente, se você tentar colocar um elemento filho que não tenha um valor de chave em um ResourceDictionary, isso gerará uma exceção de análise XAML ou um Windows Runtimeexception. A condição de exceção também pode ser indicada como um aviso por superfícies de design XAML. No entanto, há três casos notáveis em que um elemento ResourceDictionarychild não exigirá um valor de atributo x:Key:

• Um recurso Style pode usar seu valor TargetType como a chave de recurso implícita. Para obter mais informações sobre como as chaves implícitas para estilos e modelos de controle funcionam, consulte Controles de estilo.
• Os elementos ResourceDictionary com valores de origem que representam os valores ResourceDictionary.MergedDictionaries não podem ter um atributo x:Key no ResourceDictionary. Em cada arquivo de dicionário mesclado , (aquele referenciado pelo URI como sua Origem), você precisa de chaves para cada recurso.
• O atributo x:Name pode ser usado em vez do atributo x:Key, por motivos herdados. No entanto, o atributo x:Name por si só não habilita a pesquisa de recursos XAML desse item. A convenção de identificação do atributo x:Name é usada para determinados cenários, como definir animações com storyboard. Para obter mais informações, consulte atributo x:Name.

Iterando por meio de um ResourceDictionary

Você pode iterar por meio de um ResourceDictionary em C# ou Microsoft Visual Basic. Em muitos casos, como o uso da sintaxe foreach , o compilador faz essa conversão para você e você não precisará converter IEnumerable explicitamente. Se você precisar converter explicitamente, por exemplo, se quiser chamar GetEnumerator, converta para IEnumerable<T> com um Objeto KeyValuePair<, Restrição de objeto> .

ResourceDictionary e Microsoft Visual Studio

O Microsoft Visual Studio fornece uma opção de página Adicionar Novo Item para um dicionário de recursos. Use essa opção sempre que quiser definir um novo dicionário de recursos XAML solto, por exemplo, para servir como a origem de um dicionário mesclado. O Microsoft Visual Studio também adiciona um dicionário de recursos XAML solto ao projeto sempre que você usa Adicionar Novo Item para criar um controle modelo. Esse dicionário de recursos fornece os modelos de tema padrão. O Microsoft Visual Studio poderá criar um novo ResourceDictionary para você em seu XAML se você estiver editando cópias de estilos ou modelos e um ResourceDictionary para o local de recurso escolhido (aplicativo, página ou autônomo) ainda não existir.

Anotações sobre a sintaxe XAML

Observe que a sintaxe da coleção implícita XAML para ResourceDictionary não inclui um elemento de objeto para o ResourceDictionary. Este é um exemplo de sintaxe de coleção implícita XAML; uma marca que representa o elemento de coleção pode ser omitida. Os elementos adicionados como itens à coleção são especificados como elementos filho de um elemento de propriedade de uma propriedade cujo tipo subjacente dá suporte a um método Add de dicionário/mapa.

Para um dicionário de recursos mesclado, você precisa declarar explicitamente um elemento de objeto ResourceDictionary, para que você também possa declarar o elemento de propriedade ResourceDictionary.MergedDictionaries e Source. Portanto, há um mínimo de dois elementos de objeto ResourceDictionary envolvidos e você usa essa sintaxe.

<ResourceDictionary>
  <ResourceDictionary.MergedDictionaries>
    <ResourceDictionary Source="uri"/>
    ...
  </ResourceDictionary.MergedDictionaries>
...
</ResourceDictionary>

Nessa sintaxe, o ResourceDictionary externo é o ResourceDictionary primário. O ResourceDictionary interno é o ResourceDictionary que está sendo mesclado.

Para o uso implícito da coleção, o espaço reservado conforme apropriado para a propriedade FrameworkElement.Resources é mostrado. Você também pode usar esse uso de coleção implícita para a propriedade Application.Resources ou potencialmente para uma propriedade personalizada que usa ResourceDictionary como seu tipo de propriedade.

Tipos compartilháveis e tipos UIElement

Um dicionário de recursos é uma técnica para definir tipos compartilháveis e valores desses tipos em XAML. Nem todos os tipos ou valores são adequados para uso de um ResourceDictionary. Exemplos de tipos em que o compartilhamento tem suporte incluem Estilo, qualquer subclasse FrameworkTemplate , os tipos de dados intrínsecos XAML, pincéis, cores e transformações. Para obter mais informações sobre quais tipos são considerados compartilháveis, consulte Referências de recursos ResourceDictionary e XAML. Em geral, os tipos derivados de UIElement não são compartilháveis, a menos que eles venham de modelos e aplicação de um modelo em uma instância de controle específica. Excluindo o caso de modelo, espera-se que um UIElement exista em apenas um lugar em uma árvore de objetos depois de instanciado e ter um UIElement compartilhável potencialmente violaria esse princípio.

Na prática, a grande maioria dos recursos definidos em um ResourceDictionary será uma destas:

• Controle modelos para um controle, incluindo seus estados visuais.
• Estilos de suporte para partes de controles
• Estilos para elementos que fazem parte da interface do usuário típica do aplicativo, mas não são controles, como TextBlock
• Modelos de dados para controles e painéis que usam associação de dados
• Valores de pincel específicos, principalmente SolidColorBrush
• Cadeias de caracteres ou outras constantes que nunca precisam ser localizadas (cadeias de caracteres e constantes que precisam ser localizadas não devem estar em um ResourceDictionary; para obter mais informações, consulte Início Rápido: Traduzindo recursos da interface do usuário)

Acessando um objeto ResourceDictionary no código

A API que seu código usa para acessar os recursos em um ResourceDictionary depende de qual linguagem de programação você usa:

• Para C# ou Microsoft Visual Basic, você usa a API que implementa IDictionary<TKey, TValue> e IEnumerable<T>. Por exemplo, TryGetValue ou o indexador item .
• Para extensões de componente do Visual C++ (C++/CX), você usa a API que implementa IMap<K,V> e IIterable. Por exemplo, Pesquisa.
• A API que não faz parte do suporte à coleção, como Source, é a mesma em todos os idiomas.

Para obter mais informações sobre como usar ResourceDictionary no código, consulte a seção "Usando um ResourceDictionary do código" das referências de recursos ResourceDictionary e XAML.

Recursos do sistema

Alguns recursos do sistema fazem referência a valores de recursos do sistema como um subvalor adjacente. Um recurso do sistema é um valor de recurso especial que não pode ser encontrado em nenhum dicionário de recursos XAML. 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.

Anotações para versões anteriores

Otimização de carregamento de recursos no Windows 8.1

Começando com Windows 8.1, há uma otimização de carregamento de recursos habilitada pelo modelo de aplicativo e pelo analisador XAML Windows Runtime. Para Windows 8, o analisador XAML carregou recursos de app.xaml e criou cada um deles como objetos como parte da inicialização. Isso não era muito eficiente se houvesse grandes dicionários lá. Além disso, esses recursos incluíam os itens que eram necessários para os três temas, e dois dos três temas nem sequer estariam ativos. Começando com Windows 8.1, o analisador XAML só cria os recursos quando eles são solicitados especificamente. A solicitação pode vir de outros recursos ou do aplicativo ou da página XAML conforme cada um é carregado. Esse comportamento do analisador minimiza o tempo necessário para ler o dicionário no nível do aplicativo no momento da inicialização e permite que a primeira página do aplicativo seja carregada mais rapidamente na maioria dos casos. Os recursos necessários para outros temas inativos no momento só serão carregados se esse tema for escolhido para se tornar o tema ativo pelo usuário. Nesse momento, qualquer recurso em que a extensão de marcação {ThemeResource} foi usada para a solicitação é recalculada com base no tema recém-ativo.

Comportamento do Windows 8

Windows 8 não tinha as otimizações descritas acima. O ResourceDictionary para Application.Resources teve que concluir a análise antes que qualquer página diferente da tela inicial pudesse ser carregada na Janela do aplicativo. Por isso, você pode ver algumas diferenças de tempo ao redirecionar seu aplicativo para Windows 8.1. O aplicativo deve estar carregando mais rápido, no entanto, talvez não seja possível isolar essa melhoria em relação a outras alterações feitas no código do aplicativo como parte do redirecionamento. Alguns dos locais em que você pode ver evidências de alterações de tempo devido ao carregamento otimizado de recursos incluem quando os construtores são chamados pelo analisador, para objetos como objetos Application , conversores ou outras classes personalizadas. 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.

Para obter mais informações sobre desempenho e fatoramento de recursos XAML, consulte Otimizar sua marcação XAML.

Construtores

ResourceDictionary()

Inicializa uma nova instância da classe ResourceDictionary .

Propriedades

Dispatcher	Obtém o CoreDispatcher ao qual esse objeto está associado. O CoreDispatcher representa uma instalação que pode acessar DependencyObject no thread da interface do usuário mesmo que o código seja iniciado por um thread que não seja da interface do usuário. (Herdado de DependencyObject)
MergedDictionaries	Obtém uma coleção dos dicionários ResourceDictionary que constituem os vários dicionários de recursos nos dicionários mesclados.
Size	Obtém o número de elementos contidos na coleção.
Source	Obtém ou define um URI (Uniform Resource Identifier) que fornece o local de origem de um dicionário de recursos mesclado.
ThemeDictionaries	Obtém uma coleção de dicionários de recursos mesclados que são especificamente chaveados e compostos para abordar cenários de tema, por exemplo, fornecendo valores de tema para "HighContrast".

Métodos

Clear()	Remove todos os itens deste ResourceDictionary.
ClearValue(DependencyProperty)	Limpa o valor local de uma propriedade de dependência. (Herdado de DependencyObject)
First()	Retorna um iterador para os itens da coleção.
GetAnimationBaseValue(DependencyProperty)	Retorna qualquer valor base estabelecido para uma propriedade de dependência, que se aplicaria nos casos em que uma animação não está ativa. (Herdado de DependencyObject)
GetValue(DependencyProperty)	Retorna o valor efetivo atual de uma propriedade de dependência de um DependencyObject. (Herdado de DependencyObject)
GetView()	Recupera uma exibição no ResourceDictionary.
HasKey(Object)	Retorna se o ResourceDictionary tem uma entrada com a chave solicitada.
Insert(Object, Object)	Adiciona uma nova entrada ao ResourceDictionary.
Lookup(Object)	Retorna o valor da chave solicitada, se houver uma entrada com essa chave.
ReadLocalValue(DependencyProperty)	Retorna o valor local de uma propriedade de dependência, se um valor local for definido. (Herdado de DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	Registra uma função de notificação para escutar alterações em uma DependencyProperty específica nesta instância dependencyObject . (Herdado de DependencyObject)
Remove(Object)	Remove um item específico do ResourceDictionary.
SetValue(DependencyProperty, Object)	Define o valor local de uma propriedade de dependência em um DependencyObject. (Herdado de DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	Cancela uma notificação de alteração que foi registrada anteriormente chamando RegisterPropertyChangedCallback. (Herdado de DependencyObject)

Confira também

• Referências de ResourceDictionary e recursos XAML
• Amostra de recursos e localização de aplicativos
• Extensão de marcação {ThemeResource}
• Extensão de marcação {StaticResource}
• Atributo x:Key