ResourceDictionary Classe

Definição

Namespace:

Microsoft.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 a extensão de marcação {ThemeResource}. Você também pode acessar recursos com código, mas isso é menos comum.

/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 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(Microsoft.UI.Xaml.WinUIContract), 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

Microsoft.UI.Xaml.ColorPaletteResources

Microsoft.UI.Xaml.Controls.XamlControlsResources

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>>

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 a extensão 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 ResourceDictionary tipo é usado como o valor de duas propriedades, FrameworkElement.Resources e Application.Resources, que são importantes para a estrutura geral de um aplicativo SDK do Aplicativo Windows. 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 ResourceDictionary elemento subordinado ao Page.Resources elemento property, 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 Style 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 Style propriedades no Microsoft Visual Studio. Em seguida, você pode usar o recurso com a Style frequência que desejar na página para impor a uniformidade.

<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

No XAML, as chaves para ResourceDictionary itens 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 uma exceção de Windows Runtime. 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 ResourceDictionary elemento filho 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 ResourceDictionary elementos com valores de origem que representam os valores ResourceDictionary.MergedDictionaries não podem ter um atributo x:Key em 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#. Em muitos casos, como o uso foreach da sintaxe, 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 com uma KeyValuePair<Object,Object> restrição.

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 ResourceDictionary elemento de objeto, para que você também possa declarar o elemento de propriedade ResourceDictionary.MergedDictionaries e Source. Portanto, há um mínimo de dois ResourceDictionary elementos de objeto envolvidos e você usa essa sintaxe.

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

Nessa sintaxe, o externo ResourceDictionary é o principal ResourceDictionary. O interior ResourceDictionary é 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. Geralmente, os tipos derivados de UIElement não são compartilháveis, a menos que 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:

• Modelos de controle 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 específicos do Brush , 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#, você usa a API que implementa IDictionary<TKey, TValue> e IEnumerable. Por exemplo, TryGetValue ou o indexador item .
• 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" de 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.

Construtores

ResourceDictionary()

Inicializa uma nova instância da classe ResourceDictionary .

Propriedades

Dispatcher	Sempre retorna null em um aplicativo SDK do Aplicativo Windows. Em vez disso, use DispatcherQueue . (Herdado de DependencyObject)
DispatcherQueue	Obtém o ao DispatcherQueue qual esse objeto está associado. O DispatcherQueue representa uma instalação que pode acessar o 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