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

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 valores iniciales para 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 style 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 con tanta frecuencia como desee 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 . Xaml coloca dos elementos Style en el diccionario de recursos, lo que los pone a disposición 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 tener acceso 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. Después, 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 style . 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 style 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 "Merged resource dictionaries" (Diccionarios de recursos combinados) de Referencias a recursos ResourceDictionary y XAML.

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 un ResourceDictionary, se produce una excepción de análisis XAML o una excepción windows Runtimeexception. La condición de excepción también se puede observar 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, consulta Aplicar estilos a controles.
• Los elementos ResourceDictionary con valores source que representan 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 la definición de animaciones con guion gráfico. Para obtener más información, consulta el atributo x:Name.

Iteración mediante 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 en IEnumerable<T> con una restricción KeyValuePair<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 dinámico, 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 resourceDictionary nuevo para ti en el XAML si estás editando copias de estilos o plantillas y un ResourceDictionary para la 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, el ResourceDictionary externo es el resourceDictionary principal. ResourceDictionary interno es resourceDictionary que se va a combinar.

Para el uso implícito de la colección, se muestra el marcador de posición según corresponda para la propiedad FrameworkElement.Resources . También puede usar este uso implícito de la colección 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 a 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 un solo lugar en un árbol de objetos después de crear una instancia 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 un 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
• Las cadenas u otras constantes que nunca tienen que localizarse (cadenas y constantes que deben localizarse no deben estar localizadas 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 .
• En el caso de las extensiones de componentes de Visual C++ (C++/CX), use la API que implementa IMap<K,V> e IIterable. 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" (Uso de resourceDictionary a partir del código) de Referencias a recursos ResourceDictionary y XAML.

Recursos del sistema

Algunos recursos de temas hacen referencia a valores de recursos del sistema como un subvalor subyacente. Un recurso del sistema es un valor de recurso especial que no se encuentra en ningún diccionario de recursos XAML. El comportamiento de estos valores se basa en que el XAML de Windows Runtime permite reenviar valores desde el propio sistema y representarlos de forma que un recurso XAML pueda hacer referencia a ellos.

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 grandes diccionarios allí. Además, esos recursos incluían los elementos que necesitaban 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 la aplicación o de la página XAML 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 el momento del 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 actualmente inactivos 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 vuelve a calcular 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 finalizar el análisis 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 establecer 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 de la redestinación. Algunos de los lugares donde es posible que vea evidencia de cambios de tiempo debido a la carga de recursos optimizada incluyen cuando el analizador llama a los constructores, para objetos como objetos Application , convertidores u otras clases personalizadas. Las aplicaciones compiladas para Windows 8 que se ejecuten en Windows 8.1 siguen usando el comportamiento de Windows 8.

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

Constructores

Propiedades

Métodos

Se aplica a

Consulte también

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