ResourceDictionary Clase

Definición

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

Herencia

Object IInspectable DependencyObject ResourceDictionary

Derivado

Windows.UI.Xaml.ColorPaletteResources

Atributos

ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Implementaciones

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

Requisitos de Windows

Requisitos	Description
Familia de dispositivos	Windows 10 (se introdujo en la versión 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (se introdujo en la versión v1.0)

Comentarios

Un diccionario de recursos es un repositorio para recursos XAML, como estilos, que usa la aplicación. Los recursos se definen en XAML y, a continuación, se pueden recuperar en XAML mediante la extensión de marcado {StaticResource} y las extensiones de marcado {ThemeResource} . También puede acceder a los recursos con código, pero eso es menos común. Puedes usar recursos para exigir que determinados valores, como colores de pincel o medidas de píxeles, se usen de forma coherente en toda la aplicación. Para obtener más información sobre el uso eficaz de diccionarios de recursos, consulta Referencias a recursos ResourceDictionary y XAML.

Usos de elementos ResourceDictionary

El tipo ResourceDictionary se usa como valor de dos propiedades, FrameworkElement.Resources y Application.Resources, que son importantes para la estructura general de una aplicación para UWP. Los archivos XAML que obtengas de una plantilla de proyecto inicial para una aplicación comenzarán con los valores iniciales de FrameworkElement.Resources y el archivo app.xaml podría comenzar con valores iniciales para Application.Resources. Exactamente qué recursos se definen allí depende de la plantilla de inicio del proyecto que use.

Este XAML muestra el uso de una propiedad FrameworkElement.Resources . En este caso , FrameworkElement es una página. No hay ningún elemento ResourceDictionary subordinado al elemento de propiedad Page.Resources, pero su presencia está implícita; para obtener más información, consulta la sección "Notas sobre la sintaxis XAML" a continuación. El XAML coloca un estilo en ResourceDictionary con un valor de atributo x:Key de "TextBlockStyle1". Más abajo en el XAML, la extensión de marcado {StaticResource} hace referencia al estilo del diccionario de recursos para proporcionar un valor para la propiedad Style del elemento TextBlock .

El estilo como se muestra no aplica realmente ningún estilo a TextBlock, pero puede agregar propiedades Style en Microsoft Visual Studio. A continuación, puede usar el recurso Style tantas veces como quiera en la página para aplicar la uniformidad.

Puede usar Microsoft Visual Studio para crear diccionarios de recursos. Este ejemplo se creó con estos pasos: coloque un TextBlock en la superficie de diseño, haga clic con el botón derecho, elija Editar estilo / Crear vacío y, a continuación, "Este documento" para definir el nuevo recurso en 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>

Este XAML, del archivo AppPage.xaml del ejemplo AtomPub, muestra el uso de una propiedad Application.Resources . El XAML coloca dos elementos Style en el diccionario de recursos, lo que hace que estén disponibles en toda la aplicación.

<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 del archivo MainPage.xaml usa la extensión de marcado {StaticResource} para acceder a los estilos TitleStyle y 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>
 ...

Puedes factorizar los recursos en su propio archivo XAML mediante ResourceDictionary como elemento raíz del archivo. A continuación, puede incluir esos recursos en un diccionario de recursos FrameworkElement.Resources o Application.Resources . Para ello, use la propiedad ResourceDictionary.MergedDictionaries o la propiedad ResourceDictionary.ThemeDictionaries del elemento ResourceDictionary.

Este archivo, Common/Styles1.xaml, define los recursos style mediante ResourceDictionary como elemento raíz:

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

Ahora supongamos que hay otro archivo, Common/Styles2.xaml que define de forma similar los recursos de estilo . Este XAML muestra cómo combinar los recursos de esos dos archivos mediante la propiedad ResourceDictionary.MergedDictionaries para crear un diccionario de recursos Application.Resources . El XAML también define dos recursos de estilo adicionales y los combina con los recursos de los dos archivos.

<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 obtener información sobre cómo se resuelven los recursos de diccionario combinados, consulta la sección "Diccionarios de recursos combinados" de Referencias a recursos XAML y ResourceDictionary.

La propiedad x:Key

En XAML, las claves de ResourceDictionaryitems se declaran estableciendo el atributo x:Keyen elementos que representan los recursos XAML. Normalmente, si intentas colocar un elemento secundario que no tiene un valor de clave en resourceDictionary, se produce una excepción de análisis XAML o una excepción de Windows Runtimeexception. La condición de excepción también se puede anotar como una advertencia por superficies de diseño XAML. Sin embargo, hay tres casos importantes en los que un elemento ResourceDictionarychild no requerirá un valor de atributo x:Key:

• Un recurso Style puede usar su valor TargetType como clave de recurso implícita. Para obtener más información sobre cómo funcionan las claves implícitas para estilos y plantillas de control, consulte Controles de estilos.
• Los elementos ResourceDictionary con valores source que representan los valores ResourceDictionary.MergedDictionaries no pueden tener un atributo x:Key en ResourceDictionary. Dentro de cada archivo de diccionario combinado, (el al que hace referencia el URI como origen) necesita claves para cada recurso.
• El atributo x:Name se puede usar en lugar del atributo x:Key, por motivos heredados. Sin embargo, el atributo x:Name por sí mismo no habilita la búsqueda de recursos XAML de ese elemento. La convención de identificación de atributos x:Name se usa para determinados escenarios, como definir animaciones con guion gráfico. Para obtener más información, consulte el atributo x:Name.

Iteración a través de resourceDictionary

Puede recorrer en iteración un ResourceDictionary en C# o Microsoft Visual Basic. En muchos casos, como el uso de la sintaxis foreach , el compilador realiza esta conversión por usted y no tendrá que convertir a IEnumerable explícitamente. Si necesita convertir explícitamente, por ejemplo, si desea llamar a GetEnumerator, convierta a IEnumerable<T> con una restricción KeyValuePair<Object,Object> .

ResourceDictionary y Microsoft Visual Studio

Microsoft Visual Studio proporciona una opción de página Agregar nuevo elemento para un diccionario de recursos. Usa esta opción siempre que quieras definir un nuevo diccionario de recursos XAML flexible, por ejemplo, para servir como origen de un diccionario combinado. Microsoft Visual Studio también agrega un diccionario de recursos XAML flexible al proyecto cada vez que se usa Agregar nuevo elemento para crear un control con plantilla. Este diccionario de recursos proporciona las plantillas de tema predeterminadas. Microsoft Visual Studio puede crear un nuevo ResourceDictionary para ti en tu XAML si estás editando copias de estilos o plantillas y un ResourceDictionary para tu ubicación de recursos elegida (aplicación, página o independiente) aún no existe.

Notas sobre la sintaxis XAML

Observe que la sintaxis de la colección implícita XAML para ResourceDictionary no incluye un elemento de objeto para ResourceDictionary. Este es un ejemplo de sintaxis de colección implícita xaml; Se puede omitir una etiqueta que representa el elemento de colección. Los elementos que se agregan como elementos a la colección se especifican como elementos secundarios de un elemento de propiedad de una propiedad cuyo tipo subyacente admite un método dictionary/map Add .

Para un diccionario de recursos combinado, debe declarar explícitamente un elemento de objeto ResourceDictionary, de modo que también pueda declarar el elemento de propiedad ResourceDictionary.MergedDictionaries y Source. Por lo tanto, hay un mínimo de dos elementos de objeto ResourceDictionary implicados y se usa esta sintaxis.

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

En esta sintaxis, resourceDictionary externo es resourceDictionary principal. ResourceDictionary interno es resourceDictionary que se va a combinar.

Para el uso de la colección implícita, se muestra el marcador de posición según corresponda para la propiedad FrameworkElement.Resources . También puede usar este uso de colección implícita para la propiedad Application.Resources o potencialmente para una propiedad personalizada que use ResourceDictionary como su tipo de propiedad.

Tipos que se pueden compartir y tipos UIElement

Un diccionario de recursos es una técnica para definir tipos y valores que se pueden compartir de estos tipos en XAML. No todos los tipos o valores son adecuados para su uso desde resourceDictionary. Entre los ejemplos de tipos en los que se admite el uso compartido se incluyen Style, cualquier subclase FrameworkTemplate , los tipos de datos intrínsecos xaml, pinceles, colores y transformaciones. Para obtener más información sobre qué tipos se consideran que se pueden compartir, consulta Referencias de recursos ResourceDictionary y XAML. Por lo general, los tipos derivados de UIElement no se pueden compartir a menos que procedan de plantillas y aplicaciones de una plantilla en una instancia de control específica. Excluyendo el caso de plantilla, se espera que un UIElement exista en solo un lugar en un árbol de objetos después de crear una instancia de y que se pueda compartir un UIElement podría infringir este principio.

En la práctica, la gran mayoría de los recursos definidos en resourceDictionary será uno de estos:

• Plantillas de control para un control, incluidos sus estados visuales.
• Estilos auxiliares para partes de controles
• Estilos para elementos que forman parte de la interfaz de usuario de la aplicación típica, pero que no son controles, como TextBlock
• Plantillas de datos para controles y paneles que usan el enlace de datos
• Valores específicos de Brush , principalmente SolidColorBrush
• Cadenas u otras constantes que nunca necesitan localizarse (cadenas y constantes que no deben localizarse no deben estar en resourceDictionary; para obtener más información, consulte Inicio rápido: Traducción de recursos de interfaz de usuario)

Acceso a un objeto ResourceDictionary en el código

La API que usa el código para acceder a los recursos de un ResourceDictionary depende del lenguaje de programación que use:

• Para C# o Microsoft Visual Basic use la API que implementa IDictionary<TKey,TValue> e IEnumerable<T>. Por ejemplo, TryGetValue o el indexador Item .
• Para las extensiones de componentes de Visual C++ (C++/CX), use la API que implementa IMap<K,V> e IIterable<T>. Por ejemplo, Búsqueda.
• La API que no forma parte de la compatibilidad con la recopilación, como Source, es la misma en todos los idiomas.

Para obtener más información sobre cómo usar ResourceDictionary en el código, consulta la sección "Using a ResourceDictionary from code" (Usar un resourceDictionary desde el código) de resourceDictionary y referencias de recursos XAML.

Recursos del sistema

Algunos recursos de tema hacen referencia a los valores de recursos del sistema como subvalor subyacente. Un recurso del sistema es un valor de recurso especial que no se encuentra en ningún diccionario de recursos XAML. Estos valores se basan en el comportamiento de la compatibilidad con XAML de Windows Runtime para reenviar valores desde el propio sistema y representarlos en un formulario al que puede hacer referencia un recurso XAML.

Notas de las versiones anteriores

Optimización de carga de recursos en Windows 8.1

A partir de Windows 8.1, hay una optimización de carga de recursos habilitada por el modelo de aplicación y el analizador XAML de Windows Runtime. Para Windows 8, el analizador XAML cargó los recursos de app.xaml y creó cada uno de ellos como objetos como parte del inicio. Eso no era muy eficaz si había diccionarios grandes allí. Además, esos recursos incluían los elementos necesarios para los tres temas, y dos de los tres temas ni siquiera estarían activos. A partir de Windows 8.1, el analizador XAML solo crea los recursos cuando se solicitan específicamente. La solicitud puede provenir de otros recursos o de xaml de la aplicación o de la página a medida que se carga cada uno. Este comportamiento del analizador minimiza el tiempo necesario para leer el diccionario de nivel de aplicación en tiempo de inicio y permite que la primera página de la aplicación se cargue más rápido en la mayoría de los casos. Los recursos necesarios para otros temas inactivos actualmente solo se cargan si el usuario elige ese tema para convertirse en el tema activo. En ese momento, cualquier recurso en el que se usó la extensión de marcado {ThemeResource} para la solicitud se recalcula en función del tema recién activo.

comportamiento de Windows 8

Windows 8 no tenía las optimizaciones descritas anteriormente. ResourceDictionary para Application.Resources tuvo que terminar de analizar antes de que cualquier página que no sea la pantalla de presentación pudiera cargarse en la ventana de la aplicación. Debido a esto, es posible que vea algunas diferencias en el tiempo al volver a configurar la aplicación para Windows 8.1. La aplicación debe cargarse más rápido, pero es posible que no sea posible aislar esta mejora frente a otros cambios realizados en el código de la aplicación como parte del destino. Algunos de los lugares en los que puede ver evidencias de cambios de tiempo debido a la carga de recursos optimizadas incluyen cuando el analizador llama a los constructores, para objetos como objetos Application , convertidores u otras clases personalizadas. Las aplicaciones compiladas para Windows 8 pero que se ejecutan en Windows 8.1 siguen usando el comportamiento de Windows 8.

Para obtener más información sobre el rendimiento y la factorización de recursos XAML, consulta Optimizar el marcado XAML.

Consulte también

• Referencias a ResourceDictionary y a los recursos XAML
• Recursos de aplicación y localización: ejemplo
• Extensión de marcado {ThemeResource}
• Extensión de marcado {StaticResource}
• Atributo x:Key