Referências de recursos de ResourceDictionary e XAMLResourceDictionary and XAML resource references

Você pode definir a interface do usuário ou recursos para seu aplicativo usando XAML.You can define the UI or resources for your app using XAML. Os recursos geralmente são definições de algum objeto que você espera usar mais de uma vez.Resources are typically definitions of some object that you expect to use more than once. Para fazer referência a um recurso XAML posteriormente, você precisa especificar uma chave para um recurso XAML que aja como o nome do recurso.To refer to a XAML resource later, you specify a key for a resource that acts like its name. Você pode fazer referência a um recurso em uma aplicativo ou em qualquer página XAML dentro dele.You can reference a resource throughout an app or from any XAML page within it. É possível definir seus recursos usando um elemento ResourceDictionary do XAML do Windows Runtime.You can define your resources using a ResourceDictionary element from the Windows Runtime XAML. Em seguida, você pode referenciar seus recursos usando uma extensão de marcação StaticResource ou ThemeResource.Then, you can reference your resources by using a StaticResource markup extension or ThemeResource markup extension.

Os elementos XAML que podem ser declarados com mais frequência como recursos XAML incluem Style, ControlTemplate, componentes de animação e subclasses Brush.The XAML elements you might want to declare most often as XAML resources include Style, ControlTemplate, animation components, and Brush subclasses. Aqui, explicaremos como definir um elemento ResourceDictionary e os recursos inseridos, e também como os recursos XAML se relacionam com outros recursos definidos como parte do aplicativo ou do pacote do aplicativo.Here, we explain how to define a ResourceDictionary and keyed resources, and how XAML resources relate to other resources that you define as part of your app or app package. Também explicaremos as características avançadas do dicionário de recursos como MergedDictionaries e ThemeDictionaries.We also explain resource dictionary advanced features such as MergedDictionaries and ThemeDictionaries.

Pré-requisitosPrerequisites

Presumimos que você entende a marcação XAML e leu a Visão geral do XAML.We assume that you understand XAML markup and have read the XAML overview.

Definir e usar recursos XAMLDefine and use XAML resources

Recursos XAML são objetos referenciados na marcação mais de uma vez.XAML resources are objects that are referenced from markup more than once. Os recursos são definidos em um ResourceDictionary, normalmente em um arquivo separado ou na parte superior da página de marcação, como esta.Resources are defined in a ResourceDictionary, typically in a separate file or at the top of the markup page, like this.

<Page
    x:Class="MSDNSample.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <Page.Resources>
        <x:String x:Key="greeting">Hello world</x:String>
        <x:String x:Key="goodbye">Goodbye world</x:String>
    </Page.Resources>

    <TextBlock Text="{StaticResource greeting}" Foreground="Gray" VerticalAlignment="Center"/>
</Page>

Neste exemplo:In this example:

  • <Page.Resources>…</Page.Resources> - Define o dicionário de recursos.<Page.Resources>…</Page.Resources> - Defines the resource dictionary.
  • <x:String> - Define o recurso com a chave "greeting".<x:String> - Defines the resource with the key "greeting".
  • {StaticResource greeting} – pesquisa o recurso com a chave "greeting", que é atribuída à propriedade Text de TextBlock.{StaticResource greeting} - Looks up the resource with the key "greeting", which is assigned to the Text property of the TextBlock.

Observação  Não confunda os conceitos relacionados a ResourceDictionary com a ação de compilação Resource, arquivos de recursos (.resw) ou outros "recursos" que são abordados no contexto de estruturação do projeto de código que produz seu pacote do aplicativo.Note  Don't confuse the concepts related to ResourceDictionary with the Resource build action, resource (.resw) files, or other "resources" that are discussed in the context of structuring the code project that produces your app package.

Os recursos não precisam ser cadeias de caracteres; eles podem ser qualquer objeto compartilhável, como estilos, modelos, pincéis e cores.Resources don't have to be strings; they can be any shareable object, such as styles, templates, brushes, and colors. Entretanto, controles, formas e outros FrameworkElements não são compartilháveis, então não podem ser declarados como recursos reutilizáveis.However, controls, shapes, and other FrameworkElements are not shareable, so they can't be declared as reusable resources. Para saber mais sobre compartilhamento, consulte a seção Recursos XAML devem ser compartilháveis mais adiante neste tópico.For more info about sharing, see the XAML resources must be shareable section later in this topic.

Aqui, um pincel e uma cadeia de caracteres são declarados como recursos e usados pelos controles em uma página.Here, both a brush and a string are declared as resources and used by controls in a page.

<Page
    x:Class="SpiderMSDN.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <Page.Resources>
        <SolidColorBrush x:Key="myFavoriteColor" Color="green"/>
        <x:String x:Key="greeting">Hello world</x:String>
    </Page.Resources>

    <TextBlock Foreground="{StaticResource myFavoriteColor}" Text="{StaticResource greeting}" VerticalAlignment="Top"/>
    <Button Foreground="{StaticResource myFavoriteColor}" Content="{StaticResource greeting}" VerticalAlignment="Center"/>
</Page>

Todos os recursos precisam ter uma chave.All resources need to have a key. Normalmente, essa chave é uma cadeia de caracteres definida com x:Key="myString".Usually that key is a string defined with x:Key="myString". Entretanto, há outras maneiras de especificar uma chave:However, there are a few other ways to specify a key:

  • Style e ControlTemplate exigem um TargetType e usarão o TargetType como a chave se x:Key não for especificado.Style and ControlTemplate require a TargetType, and will use the TargetType as the key if x:Key is not specified. Nesse caso, a chave é o objeto Type mesmo, não uma cadeia de caracteres.In this case, the key is the actual Type object, not a string. (Consulte exemplos abaixo.)(See examples below)
  • Os recursos DataTemplate com um TargetType usarão o TargetType como a chave se x:Key não for especificado.DataTemplate resources that have a TargetType will use the TargetType as the key if x:Key is not specified. Nesse caso, a chave é o objeto Type mesmo, não uma cadeia de caracteres.In this case, the key is the actual Type object, not a string.
  • Pode ser usado x:Name em vez de x:Key.x:Name can be used instead of x:Key. Entretanto, x:Name também gera um campo code-behind para o recurso.However, x:Name also generates a code behind field for the resource. Como resultado, x:Name é menos eficiente do que x:Key, pois esse campo precisa ser inicializado quando a página é carregada.As a result, x:Name is less efficient than x:Key because that field needs to be initialized when the page is loaded.

A extensão de marcação StaticResource pode recuperar recursos apenas com um nome de cadeia de caracteres (x:Key ou x:Name).The StaticResource markup extension can retrieve resources only with a string name (x:Key or x:Name). Porém, a estrutura XAML também procura recursos de estilo implícito (aqueles que usam TargetType em vez de x:Key ou x:Name) quando ela decide o estilo e o modelo a serem usados para um controle que não definiu as propriedades Style e ContentTemplate ou ItemTemplate.However, the XAML framework also looks for implicit style resources (those which use TargetType rather than x:Key or x:Name) when it decides which style & template to use for a control that hasn't set the Style and ContentTemplate or ItemTemplate properties.

Aqui, Style tem uma chave implícita typeof(Button) e, desde que Button na parte inferior da página não especifique uma propriedade Style, ele procura um estilo com a chave typeof(Button) :Here, the Style has an implicit key of typeof(Button), and since the Button at the bottom of the page doesn't specify a Style property, it looks for a style with key of typeof(Button):

<Page
    x:Class="MSDNSample.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <Page.Resources>
        <Style TargetType="Button">
            <Setter Property="Background" Value="Red"/>
        </Style>
    </Page.Resources>
    <Grid>
       <!-- This button will have a red background. -->
       <Button Content="Button" Height="100" VerticalAlignment="Center" Width="100"/>
    </Grid>
</Page>

Para saber mais sobre estilos implícitos e como eles funcionam, consulte Aplicando estilos a controles e Modelos de controle.For more info about implicit styles and how they work, see Styling controls and Control templates.

Pesquisar recursos no códigoLook up resources in code

Você acessa membros do dicionário de recursos como qualquer outro dicionário.You access members of the resource dictionary like any other dictionary.

Aviso

Quando você executa uma pesquisa de recursos no código, somente os recursos no dicionário Page.Resources são examinados.When you perform a resource lookup in code, only the resources in the Page.Resources dictionary are looked at. Ao contrário da extensão de marcação StaticResource, o código não fará fallback para o dicionário Application.Resources se os recursos não forem encontrados no primeiro dicionário.Unlike the StaticResource markup extension, the code doesn't fall back to the Application.Resources dictionary if the resources aren’t found in the first dictionary.

 

Este exemplo mostra como recuperar o recurso redButtonStyle do dicionário de recursos de uma página:This example shows how to retrieve the redButtonStyle resource out of a page’s resource dictionary:

<Page
    x:Class="MSDNSample.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <Page.Resources>
        <Style TargetType="Button" x:Key="redButtonStyle">
            <Setter Property="Background" Value="red"/>
        </Style>
    </Page.Resources>
</Page>
    public sealed partial class MainPage : Page
    {
        public MainPage()
        {
            this.InitializeComponent();
            Style redButtonStyle = (Style)this.Resources["redButtonStyle"];
        }
    }
    MainPage::MainPage()
    {
        InitializeComponent();
        Windows::UI::Xaml::Style style = Resources().TryLookup(winrt::box_value(L"redButtonStyle")).as<Windows::UI::Xaml::Style>();
    }

Para pesquisar recursos em todo o aplicativo no código, use Application.Current.Resources para obter o dicionário de recursos do aplicativo, conforme é mostrado aqui.To look up app-wide resources from code, use Application.Current.Resources to get the app's resource dictionary, as shown here.

<Application
    x:Class="MSDNSample.App"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:SpiderMSDN">
    <Application.Resources>
        <Style TargetType="Button" x:Key="appButtonStyle">
            <Setter Property="Background" Value="red"/>
        </Style>
    </Application.Resources>

</Application>
    public sealed partial class MainPage : Page
    {
        public MainPage()
        {
            this.InitializeComponent();
            Style appButtonStyle = (Style)Application.Current.Resources["appButtonStyle"];
        }
    }
    MainPage::MainPage()
    {
        InitializeComponent();
        Windows::UI::Xaml::Style style = Application::Current().Resources()
                                                               .TryLookup(winrt::box_value(L"appButtonStyle"))
                                                               .as<Windows::UI::Xaml::Style>();
    }

Você também pode adicionar um recurso do aplicativo no código.You can also add an application resource in code.

Há dois coisas para ter em mente ao fazer isso:There are two things to keep in mind when doing this.

  • Primeiro, você precisa adicionar os recursos antes que qualquer página tente usar o recurso.First, you need to add the resources before any page tries to use the resource.
  • Segundo, você não pode adicionar recursos ao construtor do aplicativo.Second, you can’t add resources in the App’s constructor.

Você poderá evitar os dois problemas se adicionar o recurso no método Application.OnLaunched, desta forma.You can avoid both problems if you add the resource in the Application.OnLaunched method, like this.

// App.xaml.cs
    
sealed partial class App : Application
{
    protected override void OnLaunched(LaunchActivatedEventArgs e)
    {
        Frame rootFrame = Window.Current.Content as Frame;
        if (rootFrame == null)
        {
            SolidColorBrush brush = new SolidColorBrush(Windows.UI.Color.FromArgb(255, 0, 255, 0)); // green
            this.Resources["brush"] = brush;
            // … Other code that VS generates for you …
        }
    }
}
// App.cpp

void App::OnLaunched(LaunchActivatedEventArgs const& e)
{
    Frame rootFrame{ nullptr };
    auto content = Window::Current().Content();
    if (content)
    {
        rootFrame = content.try_as<Frame>();
    }

    // Do not repeat app initialization when the Window already has content,
    // just ensure that the window is active
    if (rootFrame == nullptr)
    {
        Windows::UI::Xaml::Media::SolidColorBrush brush{ Windows::UI::ColorHelper::FromArgb(255, 0, 255, 0) };
        Resources().Insert(winrt::box_value(L"brush"), winrt::box_value(brush));
        // … Other code that VS generates for you …

Cada FrameworkElement pode ter um ResourceDictionaryEvery FrameworkElement can have a ResourceDictionary

FrameworkElement é uma classe base da qual os controles herdam e tem uma propriedade Resources.FrameworkElement is a base class that controls inherit from, and it has a Resources property. Portanto, você pode adicionar um dicionário de recursos local a qualquer FrameworkElement.So, you can add a local resource dictionary to any FrameworkElement.

Aqui, tanto Page quanto Border têm dicionários de recursos, e ambas têm um recurso chamado "greeting".Here, both the Page and the Border have resource dictionaries, and they both have a resource called "greeting". O TextBlock chamado 'textBlock2' está dentro de Border e, portanto, sua pesquisa de recursos examina primeiro os recursos de Border, depois os recursos de Page e depois os recursos de Application.The TextBlock named 'textBlock2' is inside the Border, so its resource lookup looks first to the Border’s resources, then the Page’s resources, and then the Application resources. O TextBlock mostrará "Hola mundo".The TextBlock will read "Hola mundo".

Para acessar os recursos desse elemento no código, use a propriedade Resources do elemento.To access that element’s resources from code, use that element’s Resources property. O acesso aos recursos de um FrameworkElement no código, em vez de XAML, examinará apenas esse dicionário, não os dicionários do elemento pai.Accessing a FrameworkElement’s resources in code, rather than XAML, will look only in that dictionary, not in parent element’s dictionaries.

<Page
    x:Class="MSDNSample.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Page.Resources>
        <x:String x:Key="greeting">Hello world</x:String>
    </Page.Resources>
    
    <StackPanel>
        <!-- Displays "Hello world" -->
        <TextBlock x:Name="textBlock1" Text="{StaticResource greeting}"/>

        <Border x:Name="border">
            <Border.Resources>
                <x:String x:Key="greeting">Hola mundo</x:String>
            </Border.Resources>
            <!-- Displays "Hola mundo" -->
            <TextBlock x:Name="textBlock2" Text="{StaticResource greeting}"/>
        </Border>

        <!-- Displays "Hola mundo", set in code. -->
        <TextBlock x:Name="textBlock3"/>
    </StackPanel>
</Page>

    public sealed partial class MainPage : Page
    {
        public MainPage()
        {
            this.InitializeComponent();
            textBlock3.Text = (string)border.Resources["greeting"];
        }
    }
    MainPage::MainPage()
    {
        InitializeComponent();
        textBlock3().Text(unbox_value<hstring>(border().Resources().TryLookup(winrt::box_value(L"greeting"))));
    }

Dicionários de recursos mescladosMerged resource dictionaries

Um dicionário de recursos mesclados combina um dicionário de recursos com outro, geralmente em outro arquivo.A merged resource dictionary combines one resource dictionary into another, usually in another file.

Dica  Você pode criar um arquivo de dicionário de recursos no Microsoft Visual Studio usando a opção Adicionar > Novo Item…> Dicionário de Recursos do menu Projeto.Tip  You can create a resource dictionary file in Microsoft Visual Studio by using the Add > New Item… > Resource Dictionary option from the Project menu.

Aqui, você define um dicionário de recursos em um arquivo XAML separado chamado Dictionary1.xaml.Here, you define a resource dictionary in a separate XAML file called Dictionary1.xaml.

<!-- Dictionary1.xaml -->
<ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:MSDNSample">

    <SolidColorBrush x:Key="brush" Color="Red"/>

</ResourceDictionary>

Para usar esse dicionário, mescle-o com o dicionário de sua página:To use that dictionary, you merge it with your page’s dictionary:

<Page
    x:Class="MSDNSample.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Page.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <ResourceDictionary Source="Dictionary1.xaml"/>
            </ResourceDictionary.MergedDictionaries>

            <x:String x:Key="greeting">Hello world</x:String>

        </ResourceDictionary>
    </Page.Resources>

    <TextBlock Foreground="{StaticResource brush}" Text="{StaticResource greeting}" VerticalAlignment="Center"/>
</Page>

Aqui está o que acontece neste exemplo.Here's what happens in this example. Em <Page.Resources>, declare <ResourceDictionary>.In <Page.Resources>, you declare <ResourceDictionary>. A estrutura XAML cria implicitamente um dicionário de recursos quando você adiciona recursos a <Page.Resources>; porém, neste caso, você não quer simplesmente qualquer dicionário de recursos, mas um que contenha dicionários mesclados.The XAML framework implicitly creates a resource dictionary for you when you add resources to <Page.Resources>; however, in this case, you don’t want just any resource dictionary, you want one that contains merged dictionaries.

Portanto, você declara <ResourceDictionary> e depois adiciona elementos à sua coleção <ResourceDictionary.MergedDictionaries>.So you declare <ResourceDictionary>, then add things to its <ResourceDictionary.MergedDictionaries> collection. Cada uma dessas entradas assume a forma <ResourceDictionary Source="Dictionary1.xaml"/>.Each of those entries takes the form <ResourceDictionary Source="Dictionary1.xaml"/>. Para adicionar mais de um dicionário, basta adicionar uma entrada <ResourceDictionary Source="Dictionary2.xaml"/> após a primeira entrada.To add more than one dictionary, just add a <ResourceDictionary Source="Dictionary2.xaml"/> entry after the first entry.

Depois de <ResourceDictionary.MergedDictionaries>…</ResourceDictionary.MergedDictionaries>, você tem a opção de colocar recursos adicionais em seu dicionário principal.After <ResourceDictionary.MergedDictionaries>…</ResourceDictionary.MergedDictionaries>, you can optionally put additional resources in your main dictionary. Você usa recursos de um dicionário mesclado da mesma forma que um dicionário comum.You use resources from a merged to dictionary just like a regular dictionary. No exemplo acima, {StaticResource brush} encontra o recurso no dicionário filho/mesclado (Dictionary1.xaml), enquanto {StaticResource greeting} encontra seu recurso no dicionário da página principal.In the example above, {StaticResource brush} finds the resource in the child/merged dictionary (Dictionary1.xaml), while {StaticResource greeting} finds its resource in the main page dictionary.

Na sequência de pesquisa de recursos, um dicionário MergedDictionaries só é verificado após a verificação de todos os recursos com chave do ResourceDictionary.In the resource-lookup sequence, a MergedDictionaries dictionary is checked only after a check of all the other keyed resources of that ResourceDictionary. Depois de pesquisar esse nível, a pesquisa acessa os dicionários mesclados, e cada item em MergedDictionaries é verificado.After searching that level, the lookup reaches the merged dictionaries, and each item in MergedDictionaries is checked. Se houver vários dicionários mesclados, eles serão verificados na ordem inversa em que foram declarados na propriedade MergedDictionaries.If multiple merged dictionaries exist, these dictionaries are checked in the inverse of the order in which they are declared in the MergedDictionaries property. No exemplo seguinte, se Dictionary2.xaml e Dictionary1.xaml tiverem declarado a mesma chave, a chave de Dictionary2.xaml será usada primeiro porque é a última no conjunto MergedDictionaries .In the following example, if both Dictionary2.xaml and Dictionary1.xaml declared the same key, the key from Dictionary2.xaml is used first because it's last in the MergedDictionaries set.

<Page
    x:Class="MSDNSample.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Page.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <ResourceDictionary Source="Dictionary1.xaml"/>
                <ResourceDictionary Source="Dictionary2.xaml"/>
            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </Page.Resources>

    <TextBlock Foreground="{StaticResource brush}" Text="greetings!" VerticalAlignment="Center"/>
</Page>

No escopo de qualquer ResourceDictionary, o dicionário é verificado para confirmar a exclusividade da chave.Within the scope of any one ResourceDictionary, the dictionary is checked for key uniqueness. Entretanto, esse escopo não se estende pelos vários itens em arquivos diferentes de MergedDictionaries.However, that scope does not extend across different items in different MergedDictionaries files.

É possível usar a combinação da sequência de pesquisa e a ausência de imposição de chave exclusiva nos escopos de dicionários mesclados para criar uma sequência de valores de fallback dos recursos do ResourceDictionary.You can use the combination of the lookup sequence and lack of unique key enforcement across merged-dictionary scopes to create a fallback value sequence of ResourceDictionary resources. Por exemplo, você pode armazenar as preferências do usuário para uma determinada cor do pincel no último dicionário de recursos mesclado na sequência. Basta usar um dicionário de recursos que é sincronizado com o estado de seu aplicativo e dados de preferência do usuário.For example, you might store user preferences for a particular brush color in the last merged resource dictionary in the sequence, using a resource dictionary that synchronizes to your app's state and user preference data. No entanto, se não houver nenhuma preferência de usuário, você poderá definir essa mesma cadeia de caracteres de chave para um recurso ResourceDictionary no arquivo MergedDictionaries inicial e isso pode servir como o valor de fallback.However, if no user preferences exist yet, you can define that same key string for a ResourceDictionary resource in the initial MergedDictionaries file, and it can serve as the fallback value. Lembre-se de que qualquer valor fornecido em um dicionário de recursos principal é sempre verificado antes da verificação dos dicionários mesclados; portanto, se quiser usar a técnica de fallback, não defina esse recurso em um dicionário de recursos principal.Remember that any value you provide in a primary resource dictionary is always checked before the merged dictionaries are checked, so if you want to use the fallback technique, don't define that resource in a primary resource dictionary.

Recursos de tema e dicionários de temasTheme resources and theme dictionaries

Um ThemeResource é semelhante a um StaticResource, mas a pesquisa de recursos é reavaliada quando o tema muda.A ThemeResource is similar to a StaticResource, but the resource lookup is reevaluated when the theme changes.

Neste exemplo, você define o primeiro plano de um TextBlock como um valor do tema atual.In this example, you set the foreground of a TextBlock to a value from the current theme.

<TextBlock Text="hello world" Foreground="{ThemeResource FocusVisualWhiteStrokeThemeBrush}" VerticalAlignment="Center"/>

Um dicionário de temas é um tipo especial de dicionário mesclado que mantém os recursos que variam conforme o tema atualmente usado pelo usuário em seu dispositivo.A theme dictionary is a special type of merged dictionary that holds the resources that vary with the theme a user is currently using on his or her device. Por exemplo, o tema "claro" pode usar uma cor branca, enquanto o tema "escuro" pode usar um pincel de cor escura.For example, the "light" theme might use a white color brush whereas the "dark" theme might use a dark color brush. O pincel muda o recurso para o qual ele é resolvido; caso contrário, a composição de um controle que usa o pincel como um recurso poderia ser a mesma.The brush changes the resource that it resolves to, but otherwise the composition of a control that uses the brush as a resource could be the same. Para reproduzir o comportamento de alternância de temas em seus próprios modelos e estilos, em vez de usar MergedDictionaries como a propriedade para mesclar os itens nos dicionários principais, use a propriedade ThemeDictionaries.To reproduce the theme-switching behavior in your own templates and styles, instead of using MergedDictionaries as the property to merge items into the main dictionaries, use the ThemeDictionaries property.

Cada elemento ResourceDictionary dentro de ThemeDictionaries deve ter um valor x:Key.Each ResourceDictionary element within ThemeDictionaries must have an x:Key value. Esse valor é uma cadeia de caracteres que nomeia o tema relevante, por exemplo, "Default", "Dark", "Light" ou "HighContrast".The value is a string that names the relevant theme—for example, "Default", "Dark", "Light", or "HighContrast". Em geral, Dictionary1 e Dictionary2 definirão recursos que tenham os mesmos nomes, mas valores diferentes.Typically, Dictionary1 and Dictionary2 will define resources that have the same names but different values.

Aqui, você usa texto em vermelho para o tema claro e texto em azul para o tema escuro.Here, you use red text for the light theme and blue text for the dark theme.

<!-- Dictionary1.xaml -->
<ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:MSDNSample">

    <SolidColorBrush x:Key="brush" Color="Red"/>

</ResourceDictionary>

<!-- Dictionary2.xaml -->
<ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:MSDNSample">

    <SolidColorBrush x:Key="brush" Color="blue"/>

</ResourceDictionary>

Neste exemplo, você define o primeiro plano de um TextBlock como um valor do tema atual.In this example, you set the foreground of a TextBlock to a value from the current theme.

<Page
    x:Class="MSDNSample.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Page.Resources>
        <ResourceDictionary>
            <ResourceDictionary.ThemeDictionaries>
                <ResourceDictionary Source="Dictionary1.xaml" x:Key="Light"/>
                <ResourceDictionary Source="Dictionary2.xaml" x:Key="Dark"/>
            </ResourceDictionary.ThemeDictionaries>
        </ResourceDictionary>
    </Page.Resources>
    <TextBlock Foreground="{StaticResource brush}" Text="hello world" VerticalAlignment="Center"/>
</Page>

Para dicionários de temas, o dicionário ativo que será usado para a pesquisa de recursos muda dinamicamente sempre que a extensão de marcação ThemeResource é usada para fazer a referência e o sistema detecta uma mudança de tema.For theme dictionaries, the active dictionary to be used for resource lookup changes dynamically, whenever ThemeResource markup extension is used to make the reference and the system detects a theme change. O comportamento da pesquisa feita pelo sistema se baseia no mapeamento do tema ativo para o x:Key de um dicionário de temas específico.The lookup behavior that is done by the system is based on mapping the active theme to the x:Key of a specific theme dictionary.

Pode ser útil examinar como os dicionários de temas são estruturados nos recursos de design de XAML padrão, que são correspondentes aos modelos que o Windows Runtime usa por padrão para seus controles.It can be useful to examine the way that the theme dictionaries are structured in the default XAML design resources, which parallel the templates that the Windows Runtime uses by default for its controls. Abra os arquivos XAML em \(Arquivos de Programas)\Windows Kits\10\DesignTime\CommonConfiguration\Neutral\UAP\<SDK version>\Generic usando um editor de texto ou seu IDE.Open the XAML files in \(Program Files)\Windows Kits\10\DesignTime\CommonConfiguration\Neutral\UAP\<SDK version>\Generic using a text editor or your IDE. Observe como os dicionários de temas são definidos primeiro em generic.xaml e como cada dicionário de temas define as mesmas chaves.Note how the theme dictionaries are defined first in generic.xaml, and how each theme dictionary defines the same keys. Cada uma dessas chaves é então referenciada pelos elementos de composição nos vários elementos inseridos, os quais estão fora do dicionário de temas e foram definidos posteriormente na XAML.Each such key is then referenced by elements of composition in the various keyed elements that are outside the theme dictionaries and defined later in the XAML. Há também um arquivo themeresources.xaml à parte para o design que contém apenas os recursos de tema e modelos extras, e não os modelos de controle padrão.There's also a separate themeresources.xaml file for design that contains only the theme resources and extra templates, not the default control templates. As áreas de temas são duplicatas do que você veria em generic.xaml.The theme areas are duplicates of what you'd see in generic.xaml.

Quando você usa ferramentas de design de XAML para editar cópias de estilos e modelos, as ferramentas de design extraem seções dos dicionários de recursos de design de XAML e os colocam como cópias locais de elementos do dicionário XAML que fazem parte do seu aplicativo e do projeto.When you use XAML design tools to edit copies of styles and templates, the design tools extract sections from the XAML design resource dictionaries and place them as local copies of XAML dictionary elements that are part of your app and project.

Para saber mais e obter uma lista dos recursos do sistema e dos recursos específicos de temas que estão disponíveis para o seu aplicativo, consulte Recursos de temas XAML.For more info and for a list of the theme-specific and system resources that are available to your app, see XAML theme resources.

Comportamento de pesquisa para referências de recursos XAMLLookup behavior for XAML resource references

Comportamento de pesquisa é o termo que descreve como o sistema de recursos XAML tenta encontrar um recurso XAML.Lookup behavior is the term that describes how the XAML resources system tries to find a XAML resource. A pesquisa ocorre quando uma chave é referenciada como uma referência de recurso XAML de algum lugar na XAML do aplicativo.The lookup occurs when a key is referenced as a XAML resource reference from somewhere in the app's XAML. Primeiro, o sistema de recursos tem um comportamento previsível no que diz respeito a onde ele verificará a existência de um recurso com base na análise.First, the resources system has predictable behavior for where it will check for the existence of a resource based on scope. Se um recurso não for encontrado na análise inicial, a análise será expandida.If a resource isn't found in the initial scope, the scope expands. O comportamento de pesquisa continua em todas as localizações e escopos em que um recurso XAML poderia ser definido por um aplicativo ou pelo sistema.The lookup behavior continues on throughout the locations and scopes that a XAML resource could possibly be defined by an app or by the system. Se todas as tentativas de pesquisa de recursos possíveis falharem, em geral um erro será gerado.If all possible resource lookup attempts fail, an error often results. Normalmente, é possível eliminar esses erros durante o processo de desenvolvimento.It's usually possible to eliminate these errors during the development process.

O comportamento de pesquisa para referências de recursos XAML começa com o objeto em que o uso real foi aplicado e sua respectiva propriedade Resources.The lookup behavior for XAML resource references starts with the object where the actual usage is applied and its own Resources property. Se houver um ResourceDictionary nesse local, esse ResourceDictionary será verificado para obter um item que tenha a chave solicitada.If a ResourceDictionary exists there, that ResourceDictionary is checked for an item that has the requested key. Esse primeiro nível de pesquisa raramente é relevante porque, em geral, você não define e depois referencia um recurso no mesmo objeto.This first level of lookup is rarely relevant because you usually do not define and then reference a resource on the same object. Na verdade, não existe aqui uma propriedade Resources.In fact, a Resources property often doesn't exist here. É possível fazer referências a recursos XAML praticamente de qualquer lugar do XAML; você não está limitado às propriedades de subclasses FrameworkElement.You can make XAML resource references from nearly anywhere in XAML; you aren't limited to properties of FrameworkElement subclasses.

A sequência de pesquisa verifica o próximo objeto pai na árvore de objetos do runtime do aplicativo.The lookup sequence then checks the next parent object in the runtime object tree of the app. Se FrameworkElement.Resources existir e contiver um ResourceDictionary, o item de dicionário com a cadeia de caracteres da chave especificada será solicitado.If a FrameworkElement.Resources exists and holds a ResourceDictionary, the dictionary item with the specified key string is requested. Se o recurso for encontrado, a sequência de pesquisa será interrompida e o objeto será fornecido ao local onde a referência foi feita.If the resource is found, the lookup sequence stops and the object is provided to the location where the reference was made. Caso contrário, o comportamento de pesquisa avançará para o próximo nível pai, em direção da raiz da árvore de objetos.Otherwise, the lookup behavior advances to the next parent level towards the object tree root. A pesquisa continuará recursivamente para cima até que o elemento raiz da XAML seja alcançado, esgotando a pesquisa de todos os possíveis locais de recursos imediatos.The search continues recursively upwards until the root element of the XAML is reached, exhausting the search of all possible immediate resource locations.

Observação  É prática comum definir todos os recursos imediatos no nível da raiz de uma página, tanto para obter as vantagens desse comportamento de pesquisa de recursos como também como uma convenção do estilo de marcação XAML.Note  It is a common practice to define all the immediate resources at the root level of a page, both to take advantage of this resource-lookup behavior and also as a convention of XAML markup style.

 

Se o recurso solicitado não for encontrado nos recursos imediatos, a próxima etapa de pesquisa será verificar a propriedade Application.Resources.If the requested resource is not found in the immediate resources, the next lookup step is to check the Application.Resources property. Application.Resources é o melhor lugar para colocar qualquer recurso específico do aplicativo que seja referenciado por várias páginas, na estrutura de navegação do aplicativo.Application.Resources is the best place to put any app-specific resources that are referenced by multiple pages in your app's navigation structure.

Os modelos de controles têm outro possível local na pesquisa de referência: os dicionários de temas.Control templates have another possible location in the reference lookup: theme dictionaries. Um dicionário de temas é um único arquivo XAML que tem o elemento ResourceDictionary como raiz.A theme dictionary is a single XAML file that has a ResourceDictionary element as its root. O dicionário de temas pode ser um dicionário mesclado de Application.Resources.The theme dictionary might be a merged dictionary from Application.Resources. O dicionário de temas também pode ser o dicionário de temas específico de um controle modelo personalizado.The theme dictionary might also be the control-specific theme dictionary for a templated custom control.

Por fim, há uma pesquisa baseada nos recursos de plataforma.Finally, there is a resource lookup against platform resources. Os recursos de plataforma incluem os modelos de controle definidos para cada um dos temas da interface do usuário do sistema e que definem a aparência padrão de todos os controles usados na interface do usuário de um aplicativo do Windows Runtime.Platform resources include the control templates that are defined for each of the system UI themes, and which define the default appearance of all the controls that you use for UI in a Windows Runtime app. Os recursos da plataforma também incluem um conjunto de recursos nomeados que se relacionam à aparência e aos temas em todo o sistema.Platform resources also include a set of named resources that relate to system-wide appearance and themes. Esses recursos são tecnicamente um item MergedDictionaries e estão disponíveis para pesquisa de XAML ou código depois que o aplicativo é carregado.These resources are technically a MergedDictionaries item, and thus are available for lookup from XAML or code once the app has loaded. Por exemplo, os recursos de tema do sistema incluem um recurso chamado "SystemColorWindowTextColor" que oferece uma definição de Color para combinar a cor do texto do aplicativo com a cor do texto da janela do sistema que vem do sistema operacional e das preferências do usuário.For example, the system theme resources include a resource named "SystemColorWindowTextColor" that provides a Color definition to match app text color to a system window's text color that comes from the operating system and user preferences. Outros estilos XAML em seu aplicativo podem mencionar esse estilo, ou o seu código pode obter um valor da pesquisa de recurso (e convertê-lo em Color no caso do exemplo).Other XAML styles for your app can refer to this style, or your code can get a resource lookup value (and cast it to Color in the example case).

Para saber mais e obter uma lista dos recursos do sistema e dos recursos específicos de temas que estão disponíveis para um aplicativo do Windows em XAML, confira Recursos de temas XAML.For more info and for a list of the theme-specific and system resources that are available to a Windows app that uses XAML, see XAML theme resources.

Se a chave solicitada ainda assim não for encontrada nesses locais, ocorrerá um erro/exceção de análise XAML.If the requested key is still not found in any of these locations, a XAML parsing error/exception occurs. Em determinadas circunstâncias, a exceção de análise XAML pode ser uma exceção de tempo de execução que não é detectada nem pela ação de compilação de marcação XAML, nem pelo ambiente de design XAML.In certain circumstances, the XAML parse exception may be a run-time exception that is not detected either by a XAML markup compile action, or by a XAML design environment.

Devido ao comportamento de pesquisa em níveis dos dicionários de recursos, é possível definir deliberadamente vários itens de recursos, cada um deles com o mesmo valor de cadeia de caracteres como a chave, desde que cada recurso seja definido em um nível diferente.Because of the tiered lookup behavior for resource dictionaries, you can deliberately define multiple resource items that each have the same string value as the key, as long as each resource is defined at a different level. Ou seja, embora as chaves devam ser exclusivas em qualquer ResourceDictionary fornecido, a exigência de exclusividade não se estende à sequência do comportamento de pesquisa como um todo.In other words, although keys must be unique within any given ResourceDictionary, the uniqueness requirement does not extend to the lookup behavior sequence as a whole. Durante a pesquisa, apenas o primeiro objeto recuperado com êxito é usado para a referência de recurso XAML e, em seguida, a pesquisa para.During lookup, only the first such object that's successfully retrieved is used for the XAML resource reference, and then the lookup stops. Você poderá usar esse comportamento para solicitar o mesmo recurso XAML pela chave em várias posições dentro da XAML de seu aplicativo, mas obter recursos diferentes de volta, dependendo do escopo do qual a referência do recurso XAML foi feita e de como essa pesquisa específica se comporta.You could use this behavior to request the same XAML resource by key at various positions within your app's XAML but get different resources back, depending on the scope from which the XAML resource reference was made and how that particular lookup behaves.

Referências de encaminhamento em um ResourceDictionaryForward references within a ResourceDictionary

As referências de recursos XAML em um determinado dicionário de recursos deve fazer referência a um recurso já definido com uma chave, e esse recurso deve aparecer lexicalmente antes da referência de recurso.XAML resource references within a particular resource dictionary must reference a resource that has already been defined with a key, and that resource must appear lexically before the resource reference. Referências de encaminhamento não podem ser resolvidas por uma referência de recurso XAML.Forward references cannot be resolved by a XAML resource reference. Por isso, se usar referências de recursos estáticos XAML originadas em outro recurso, crie sua estrutura de dicionário de recursos para que os recursos que são utilizados por outros recursos sejam definidos pela primeira vez em um dicionário de recurso.For this reason, if you use XAML resource references from within another resource, you must design your resource dictionary structure so that the resources that are used by other resources are defined first in a resource dictionary.

Os recursos definidos no nível do aplicativo não podem fazer referência a recursos imediatos.Resources defined at the app level cannot make references to immediate resources. Isso equivale a uma tentativa de referência posterior, pois os recursos do aplicativo são efetivamente processados primeiro (quando o aplicativo é iniciado pela primeira vez, e antes do carregamento de qualquer conteúdo de página de navegação).This is equivalent to attempting a forward reference, because the app resources are actually processed first (when the app first starts, and before any navigation-page content is loaded). Entretanto, recursos imediatos podem fazer referência a um recurso de aplicativo, e isso pode ser uma técnica bem útil para evitar situações de referência de encaminhamento.However, any immediate resource can make a reference to an app resource, and this can be a useful technique for avoiding forward-reference situations.

Recursos XAML devem ser compartilháveisXAML resources must be shareable

Para que um objeto exista em um ResourceDictionary, esse objeto deve ser compartilhável.For an object to exist in a ResourceDictionary, that object must be shareable.

A condição de compartilhável é uma exigência porque, quando a árvore de objetos de um aplicativo é construída e usada em tempo de execução, os objetos não podem existir em vários locais da árvore.Being shareable is required because, when the object tree of an app is constructed and used at run time, objects cannot exist at multiple locations in the tree. Internamente, o sistema de recursos cria cópias de valores de recursos a serem utilizadas no gráfico de objeto de seu aplicativo quando cada recurso XAML é solicitado.Internally, the resource system creates copies of resource values to use in the object graph of your app when each XAML resource is requested.

Um ResourceDictionary e a XAML do Windows Runtime em geral dão suporte a esses objetos para uso compartilhável:A ResourceDictionary and Windows Runtime XAML in general supports these objects for shareable usage:

Também é possível usar tipos personalizados como um recurso compartilhável, se você seguir os padrões de implementação necessários.You can also use custom types as a shareable resource if you follow the necessary implementation patterns. Você define essas classes em seu código de suporte (ou em componentes de runtime que você inclui) e, depois, instancia essas classes na XAML como um recurso.You define such classes in your backing code (or in runtime components that you include) and then instantiate those classes in XAML as a resource. Exemplos: fontes de dados de objeto e implementações IValueConverter para vinculação de dados.Examples are object data sources and IValueConverter implementations for data binding.

Tipos personalizados devem ter um construtor padrão, porque é isso que um analisador XAML usa para instanciar uma classe.Custom types must have a default constructor, because that's what a XAML parser uses to instantiate a class. Os tipos personalizados usados ​​como recursos não podem ter a classe UIElement em sua herança, pois o UIElement nunca pode ser compartilhável (é sempre destinado a representar exatamente um elemento da interface do usuário que existe em uma posição no gráfico de objeto do aplicativo em runtime).Custom types used as resources can't have the UIElement class in their inheritance, because a UIElement can never be shareable (it's always intended to represent exactly one UI element that exists at one position in the object graph of your runtime app).

Escopo de uso de UserControlUserControl usage scope

Um elemento UserControl apresenta uma situação especial de comportamento de pesquisa de recursos, pois tem os conceitos inerentes ao escopo de definição e ao escopo de uso.A UserControl element has a special situation for resource-lookup behavior because it has the inherent concepts of a definition scope and a usage scope. Um UserControl que faça uma referência de recurso XAML no respectivo escopo de definição deve poder dar suporte à pesquisa desse recurso em sua própria sequência de pesquisa de escopo de definição, ou seja, ele não pode acessar recursos de aplicativo.A UserControl that makes a XAML resource reference from its definition scope must be able to support the lookup of that resource within its own definition-scope lookup sequence—that is, it cannot access app resources. Em um escopo de uso do UserControl, uma referência de recurso é tratada como se estivesse na sequência de pesquisa, em direção à respectiva raiz da página de uso (exatamente como qualquer outra referência de recurso feita em um objeto carregado em uma árvore de objetos), e ela pode acessar recursos de aplicativo.From a UserControl usage scope, a resource reference is treated as being within the lookup sequence towards its usage page root (just like any other resource reference made from an object in a loaded object tree) and can access app resources.

ResourceDictionary e XamlReader.LoadResourceDictionary and XamlReader.Load

O ResourceDictionary pode ser usado na raiz ou como parte da entrada XAML do método XamlReader.Load.You can use a ResourceDictionary as either the root or a part of the XAML input for the XamlReader.Load method. Também será possível incluir referências de recurso XAML nessa XAML se todas essas referências estiverem totalmente autocontidas na XAML enviada para carregamento.You can also include XAML resource references in that XAML if all such references are completely self-contained in the XAML submitted for loading. XamlReader.Load analisa a XAML em um contexto que não reconhece nenhum outro objeto de ResourceDictionary, nem mesmo Application.Resources.XamlReader.Load parses the XAML in a context that is not aware of any other ResourceDictionary objects, not even Application.Resources. Além disso, não use {ThemeResource} em uma XAML enviada para XamlReader.Load.Also, don't use {ThemeResource} from within XAML submitted to XamlReader.Load.

Usando um ResourceDictionary em códigoUsing a ResourceDictionary from code

A maior parte dos cenários de um ResourceDictionary é manipulada exclusivamente na XAML.Most of the scenarios for a ResourceDictionary are handled exclusively in XAML. Você declara o contêiner ResourceDictionary e os recursos contidos nele como um arquivo XAML ou conjunto de nós XAML em um arquivo de definição da interface do usuário.You declare the ResourceDictionary container and the resources within as a XAML file or set of XAML nodes in a UI definition file. E, em seguida, você usa referências de recurso XAML para solicitar esses recursos de outras partes do XAML.And then you use XAML resource references to request those resources from other parts of XAML. Ainda assim, existem alguns cenários em que o seu aplicativo talvez precise ajustar o conteúdo de um ResourceDictionary usando o código que é executado enquanto o aplicativo está em execução, ou pelo menos consultar o conteúdo de um ResourceDictionary para ver se um recurso já está definido.Still, there are certain scenarios where your app might want to adjust the contents of a ResourceDictionary using code that executes while the app is running, or at least to query the contents of a ResourceDictionary to see if a resource is already defined. Essas chamadas de código são feitas em uma instância de ResourceDictionary, portanto, recupere primeiro uma delas seja um ResourceDictionary imediato, em algum lugar da árvore de objetos obtendo FrameworkElement.Resources ou Application.Current.Resources.These code calls are made on a ResourceDictionary instance, so you must first retrieve one—either an immediate ResourceDictionary somewhere in the object tree by getting FrameworkElement.Resources, or Application.Current.Resources.

No código de C# ou do Microsoft Visual Basic, você pode referenciar um recurso de um determinado ResourceDictionary usando o indexador (Item).In C# or Microsoft Visual Basic code, you can reference a resource in a given ResourceDictionary by using the indexer (Item). Um ResourceDictionary é um dicionário de cadeias de caracteres inseridas, portanto, o indexador usa a chave de cadeia de caracteres em vez de um número inteiro.A ResourceDictionary is a string-keyed dictionary, so the indexer uses the string key instead of an integer index. No código de extensões de componentes Visual C++ (C++/CX), use Lookup.In Visual C++ component extensions (C++/CX) code, use Lookup.

Ao usar um código para examinar ou mudar um ResourceDictionary, o comportamento para APIs como Lookup ou Item não passa de recursos imediatos para recursos do aplicativo, o que é um comportamento do analisador de XAML que só acontece enquanto páginas XAML são carregadas.When using code to examine or change a ResourceDictionary, the behavior for APIs like Lookup or Item does not traverse from immediate resources to app resources; that's a XAML parser behavior that only happens as XAML pages are loaded. Em tempo de execução, o escopo para chaves é autossuficiente na instância de ResourceDictionary que você está usando no momento.At run time, scope for keys is self-contained to the ResourceDictionary instance that you are using at the time. Entretanto, esse escopo não se estende em MergedDictionaries.However, that scope does extend into MergedDictionaries.

Além disso, se você solicitar uma chave não existente no ResourceDictionary, talvez não ocorra nenhum erro; o valor de retorno poderá simplesmente ser fornecido como null.Also, if you request a key that does not exist in the ResourceDictionary, there may not be an error; the return value may simply be provided as null. Porém, você ainda poderá receber um erro se tentar usar o null retornado como um valor.You may still get an error, though, if you try to use the returned null as a value. O erro seria gerado pelo setter da propriedade, e não pela sua chamada ResourceDictionary.The error would come from the property's setter, not your ResourceDictionary call. A única maneira de evitar um erro seria se a propriedade aceitasse null como um valor válido.The only way you'd avoid an error is if the property accepted null as a valid value. Observe como esse comportamento contrasta com o comportamento de pesquisa XAML no tempo de análise da XAML; uma falha na resolução da chave fornecida pela XAML no tempo de análise resulta em um erro de análise de XAML, mesmo nos casos em que a propriedade poderia ter aceito null.Note how this behavior contrasts with XAML lookup behavior at XAML parse time; a failure to resolve the provided key from XAML at parse time results in a XAML parse error, even in cases where the property could have accepted null.

Dicionários de recursos mesclados são incluídos no escopo de índice do dicionário de recursos principal que referencia o dicionário mesclado em tempo de execução.Merged resource dictionaries are included into the index scope of the primary resource dictionary that references the merged dictionary at run time. Em outras palavras, você pode usar Item ou Lookup do dicionário principal para localizar qualquer objeto que na verdade foi definido no dicionário mesclado.In other words, you can use Item or Lookup of the primary dictionary to find any objects that were actually defined in the merged dictionary. Neste caso, o comportamento de pesquisa se parece com o comportamento de pesquisa XAML em tempo de análise: se houver vários objetos nos dicionários mesclados e cada um deles tiver a mesma chave, o objeto do último dicionário adicionado será retornado.In this case, the lookup behavior does resemble the parse-time XAML lookup behavior: if there are multiple objects in merged dictionaries that each have the same key, the object from the last-added dictionary is returned.

É possível adicionar itens a um ResourceDictionary existente chamando Add (C# ou Visual Basic) ou Insert (C++/CX).You are permitted to add items to an existing ResourceDictionary by calling Add (C# or Visual Basic) or Insert (C++/CX). Você pode adicionar os itens a recursos imediatos ou recursos do aplicativo.You could add the items to either immediate resources or app resources. Cada uma dessas chamadas de API exige uma chave, o que atende à exigência de que cada item em um ResourceDictionary deve ter uma chave.Either of these API calls requires a key, which satisfies the requirement that each item in a ResourceDictionary must have a key. Entretanto, os itens adicionados a um ResourceDictionary em tempo de execução não são relevantes para referências a recursos XAML.However, items that you add to a ResourceDictionary at run time are not relevant to XAML resource references. A pesquisa necessária para referências de recurso XAML acontece quando essa XAML é analisada pela primeira vez quando o aplicativo é carregado (ou um tema alterado é detectado).The necessary lookup for XAML resource references happens when that XAML is first parsed as the app is loaded (or a theme change is detected). Os recursos adicionados a coleções no tempo de execução não estavam disponíveis então, e alterar o ResourceDictionary não invalida um recurso já recuperado dele, mesmo que você altere o valor desse recurso.Resources added to collections at run time weren't available then, and altering the ResourceDictionary doesn't invalidate an already retrieved resource from it even if you change the value of that resource.

Também é possível remover itens de um ResourceDictionary em tempo de execução, fazer cópias parcial ou total dos itens ou executar outras operações.You also can remove items from a ResourceDictionary at run time, make copies of some or all items, or other operations. A listagem de membros do ResourceDictionary indica quais APIs estão disponíveis.The members listing for ResourceDictionary indicates which APIs are available. Observe que como o ResourceDictionary tem uma API projetada para dar suporte a suas interfaces de coleção adjacentes, as opções da sua API são diferentes, dependendo de você estar usando C# ou Visual Basic, em vez de C++/CX.Note that because ResourceDictionary has a projected API to support its underlying collection interfaces, your API options differ depending on whether you are using C# or Visual Basic versus C++/CX.

ResourceDictionary e localizaçãoResourceDictionary and localization

Um ResourceDictionary XAML pode, inicialmente, conter cadeias de caracteres que podem ser localizadas.A XAML ResourceDictionary might initially contain strings that are to be localized. Se assim for, armazene essas cadeias de caracteres como recursos de projeto, e não em um ResourceDictionary.If so, store these strings as project resources instead of in a ResourceDictionary. Retire as cadeias de caracteres da XAML e dê ao elemento proprietário um valor da diretiva x:Uid.Take the strings out of the XAML, and instead give the owning element an x:Uid directive value. Em seguida, defina um recurso em um arquivo de recursos.Then, define a resource in a resources file. Forneça um nome de recurso no formato XUIDValue.PropertyName e um valor de recurso da cadeia de caracteres que deve ser localizada.Provide a resource name in the form XUIDValue.PropertyName and a resource value of the string that should be localized.

Pesquisa de recursos personalizadaCustom resource lookup

Em cenários avançados, você pode implementar uma classe que pode ter um comportamento diferente do comportamento de pesquisa de referência de recursos XAML descrito neste tópico.For advanced scenarios, you can implement a class that can have different behavior than the XAML resource reference lookup behavior described in this topic. Para fazer isso, implemente a classe CustomXamlResourceLoader para poder acessar esse comportamento usando a extensão de marcação CustomResource markup extension para referências de recursos, em vez de usar StaticResource ou ThemeResource.To do this, you implement the class CustomXamlResourceLoader, and then you can access that behavior by using the CustomResource markup extension for resource references rather than using StaticResource or ThemeResource. A maioria dos aplicativos não terá cenários que requeiram isso.Most apps won't have scenarios that require this. Para saber mais, consulte CustomXamlResourceLoader.For more info, see CustomXamlResourceLoader.