Compartir a través de

Referencias a ResourceDictionary y a los recursos XAML

Puedes definir la interfaz de usuario o los recursos de la aplicación mediante XAML. Los recursos suelen ser definiciones de algún objeto que espera usar más de una vez. Para hacer referencia a un recurso XAML más adelante, se especifica una clave para un recurso que actúa como su nombre. Puedes hacer referencia a un recurso a través de una aplicación o desde cualquier página XAML dentro de ella. Puedes definir los recursos mediante un elemento ResourceDictionary desde el XAML de Windows Runtime. A continuación, puede hacer referencia a los recursos mediante un extensión de marcado StaticResource o extensión de marcado ThemeResource.

Es posible que los elementos XAML que quieras declarar con más frecuencia como recursos XAML incluyen Style, ControlTemplate, componentes de animación y subclases Brush . Aquí se explica cómo definir un ResourceDictionary y recursos clave, y cómo se relacionan los recursos XAML con otros recursos que definas como parte de tu aplicación o paquete de la aplicación. También se explican las características avanzadas del diccionario de recursos, como MergedDictionaries y ThemeDictionaries.

Prerrequisitos

Una comprensión sólida del marcado XAML. Recomendamos leer descripción general de XAML.

Definición y uso de recursos XAML

Los recursos de XAML son objetos a los que se hace referencia desde el marcado más de una vez. Los recursos se definen en un ResourceDictionary, normalmente en un archivo independiente o en la parte superior de la página de marcado, como este.

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

En este ejemplo:

  • <Page.Resources>…</Page.Resources> : define el diccionario de recursos.
  • <x:String> - Define el recurso con la clave "greeting".
  • : busca el recurso con la clave "greeting", que se asigna a la propiedad text de la TextBlock.

Nota:

No confunda los conceptos relacionados con ResourceDictionary con la acción de compilación de recursos, los archivos de recursos (.resw) u otros "recursos" que se describen en el contexto de estructurar el proyecto de código que genera el paquete de la aplicación.

Los recursos no tienen que ser cadenas; pueden ser cualquier objeto que se pueda compartir, como estilos, plantillas, pinceles y colores. Sin embargo, los controles, las formas y otros frameworkElementno se pueden compartir, por lo que no se pueden declarar como recursos reutilizables. Para obtener más información sobre el uso compartido, consulta la sección Los recursos XAML deben ser compartibles más adelante en este tema.

Aquí, tanto un pincel como una cadena se declaran como recursos y los usan los controles de una página.

<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 los recursos deben tener una clave. Normalmente, esa clave es una cadena definida con x:Key="myString". Sin embargo, hay otras maneras de especificar una clave:

  • estilo y ControlTemplate requieren un TargetType , y usarán el TargetType como clave de si no se especifica x:Key . En este caso, la clave es el objeto Type real, no una cadena. (Vea los ejemplos siguientes)
  • recursos de DataTemplate que tienen un TargetType usarán el TargetType de como clave si no se especifica x:Key. En este caso, la clave es el objeto Type real, no una cadena.
  • x:Name se puede usar en lugar de x:Key. Sin embargo, x:Name también genera un campo de código subyacente para el recurso. Como resultado, x:Name es menos eficaz que x:Key porque ese campo debe inicializarse cuando se carga la página.

El de extensión de marcado StaticResource de solo puede recuperar recursos con un nombre de cadena (x:Key o x:Name). Sin embargo, el marco XAML también busca recursos de estilo implícitos (aquellos que usan TargetType en lugar de x:Key o x:Name) cuando decide qué estilo y plantilla usar para un control que no ha establecido las propiedades Style y ContentTemplate o ItemTemplate.

Aquí, el estilo de tiene una clave implícita de typeof(Button)y, dado que el Botón en la parte inferior de la página no especifica una propiedad Style , busca un estilo con clave de 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 obtener más información sobre los estilos implícitos y cómo funcionan, consulta Estilos de control y Plantillas de control.

Búsqueda de recursos en el código

Puede acceder a los miembros del diccionario de recursos como cualquier otro diccionario.

Advertencia

Cuando se realiza una búsqueda de recursos en el código, solo se examinan los recursos del Page.Resources diccionario. A diferencia de la extensión de marcado StaticResource, el código no recurre al diccionario Application.Resources si los recursos no se hallan en el primer diccionario.

En este ejemplo se muestra cómo recuperar el redButtonStyle recurso fuera del diccionario de recursos de una página:

<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 buscar recursos en toda la aplicación desde código, use Application.Current.Resources para obtener el diccionario de recursos de la aplicación, como se muestra aquí.

<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>();
    }

También puede agregar un recurso de aplicación en el código.

Hay dos cosas que hay que tener en cuenta al hacer esto.

  • En primer lugar, debe agregar los recursos antes de que cualquier página intente usar el recurso.
  • En segundo lugar, no se pueden agregar recursos en el constructor de la aplicación.

Puede evitar ambos problemas si agrega el recurso en el método Application.OnLaunched , como este.

// 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 puede tener un ResourceDictionary

FrameworkElement es una clase base de la que se heredan los controles y tiene una propiedad Resources . Por lo tanto, puede agregar un diccionario de recursos local a cualquier FrameworkElement.

Aquí, tanto la Página del como el Borde del tienen diccionarios de recursos, y ambos tienen un recurso denominado "greeting". El TextBlock denominado 'textBlock2' está dentro del Border, por lo que su búsqueda de recursos primero revisa los recursos del Border, luego los recursos de la página , y finalmente los recursos de la aplicación . El TextBlock leerá "Hola mundo".

Para acceder a los recursos de ese elemento desde el código, use la propiedad Resources de ese elemento. Acceder a los recursos de un FrameworkElementen el código, en lugar de XAML, solo buscará en ese diccionario, no en los diccionarios del elemento primario.

<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"))));
    }

Diccionarios de recursos combinados

Un diccionario de recursos combinado integra un diccionario de recursos en otro, normalmente en otro archivo.

sugerencia Puede crear un archivo de diccionario de recursos en Microsoft Visual Studio mediante la opción Agregar > Nuevo elemento... > diccionario de recursos del menú Project.

Aquí, definirás un diccionario de recursos en un archivo XAML independiente denominado 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 ese diccionario, se combina con el diccionario de la página:

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

Esto es lo que sucede en este ejemplo. En <Page.Resources>, tú declaras <ResourceDictionary>. El marco XAML crea implícitamente un diccionario de recursos para ti cuando agregas recursos a <Page.Resources>; sin embargo, en este caso, no quieres solo ningún diccionario de recursos, quieres uno que contenga diccionarios combinados.

Por lo tanto, declare <ResourceDictionary>y agregue elementos a su colección <ResourceDictionary.MergedDictionaries>. Cada una de esas entradas toma la forma <ResourceDictionary Source="Dictionary1.xaml"/>. Para agregar más de un diccionario, basta con agregar una <ResourceDictionary Source="Dictionary2.xaml"/> entrada después de la primera entrada.

Después de <ResourceDictionary.MergedDictionaries>…</ResourceDictionary.MergedDictionaries>, puede colocar opcionalmente recursos adicionales en el diccionario principal. Usas los recursos de un diccionario combinado como si fuera un diccionario normal. En el ejemplo anterior, {StaticResource brush} busca el recurso en el diccionario secundario/combinado (Dictionary1.xaml), mientras {StaticResource greeting} encuentra su recurso en el diccionario de página principal.

En la secuencia de búsqueda de recursos, solo se comprueba un diccionario MergedDictionaries después de comprobar todos los demás recursos con clave de ese ResourceDictionary. Después de explorar ese nivel, la búsqueda alcanza los diccionarios combinados y se verifica cada elemento de MergedDictionaries. Si existen varios diccionarios combinados, estos diccionarios se comprueban en el orden inverso al que están declarados en la propiedad MergedDictionaries. En el ejemplo siguiente, si dictionary2.xaml y Dictionary1.xaml declararon la misma clave, la clave de Dictionary2.xaml se usa primero porque es la última en el MergedDictionaries establecido.

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

Dentro del ámbito de cualquiera de los ResourceDictionary, se comprueba la unicidad de las claves en el diccionario. Sin embargo, ese alcance no se extiende entre distintos elementos de diferentes MergedDictionaries archivos.

Puede usar la combinación de la secuencia de búsqueda y la falta de aplicación de clave única en ámbitos de diccionario combinado para crear una secuencia de valores de reserva de resourceDictionary recursos. Por ejemplo, puede almacenar preferencias de usuario para un color de pincel determinado en el último diccionario de recursos combinado de la secuencia, usando un diccionario de recursos que se sincroniza con los datos de estado y preferencias de usuario de la aplicación. Sin embargo, si aún no existe ninguna preferencia de usuario, puede definir esa misma cadena clave para un recurso de ResourceDictionary en el archivo MergedDictionaries inicial y puede servir como valor predeterminado. Recuerde que cualquier valor que proporcione en un diccionario de recursos principal siempre se comprueba antes de que se comprueben los diccionarios combinados, por lo que si desea usar la técnica de reserva, no defina ese recurso en un diccionario de recursos principal.

Recursos de temas y diccionarios de temas

ThemeResource es similar a StaticResource, pero la búsqueda de recursos se vuelve a evaluar cuando cambia el tema.

En este ejemplo, se ajusta el color de primer plano de un TextBlock a un valor del tema actual.

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

Un diccionario de temas es un tipo especial de diccionario combinado que contiene los recursos que varían con el tema que un usuario está usando actualmente en su dispositivo. Por ejemplo, el tema "claro" podría usar un pincel de color blanco, mientras que el tema "oscuro" podría usar un pincel de color oscuro. El pincel cambia el recurso al que se resuelve, pero de lo contrario, la composición de un control que usa el pincel como un recurso podría ser el mismo. Para reproducir el comportamiento de cambio de tema en sus propias plantillas y estilos, en lugar de usar MergedDictionaries como la propiedad para combinar elementos en los diccionarios principales, use la propiedad ThemeDictionaries .

Cada elemento ResourceDictionary dentro de ThemeDictionaries debe tener un valor x:Key. El valor es una cadena que asigna un nombre al tema pertinente, por ejemplo, "Default", "Dark", "Light" o "HighContrast". Normalmente, Dictionary1 y Dictionary2 definirán los recursos que tienen los mismos nombres, pero valores diferentes.

Aquí, usará texto rojo para el tema claro y el texto azul para el tema oscuro.

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

En este ejemplo, se ajusta el color de primer plano de un TextBlock a un valor del tema actual.

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

En el caso de los diccionarios de temas, el diccionario activo que se usará para la búsqueda de recursos cambia dinámicamente, siempre que se use extensión de marcado ThemeResource para hacer que la referencia y el sistema detecte un cambio de tema. El sistema realiza el comportamiento de búsqueda basándome en mapear el tema activo al x:Key de un diccionario específico de temas.

Puede ser útil examinar la forma en que los diccionarios de temas están estructurados en los recursos de diseño XAML predeterminados, que coinciden con las plantillas que usa Windows Runtime de forma predeterminada para los controles. Abra los archivos XAML en \(Program Files)\Windows Kits\10\DesignTime\CommonConfiguration\Neutral\UAP\<versión del SDK>\Generic mediante un editor de texto o tu IDE. Observe cómo los diccionarios de temas se definen primero en generic.xaml y cómo cada diccionario de temas define las mismas claves. A continuación, cada clave es referenciada por los elementos de composición en los distintos elementos con clave que están fuera de los diccionarios de temas y se definen más adelante en el XAML. También hay un archivo themeresources.xaml independiente para el diseño que contiene solo los recursos de tema y las plantillas adicionales, no las plantillas de control predeterminadas. Las áreas de tema son duplicados de lo que verías en generic.xaml.

Cuando usas herramientas de diseño XAML para editar copias de estilos y plantillas, las herramientas de diseño extraen secciones de los diccionarios de recursos de diseño XAML y las colocan como copias locales de elementos de diccionario XAML que forman parte de tu aplicación y proyecto.

Para obtener más información y obtener una lista de los recursos específicos del tema y del sistema que están disponibles para la aplicación, consulta Recursos de temas XAML.

Comportamiento de búsqueda de referencias de recursos XAML

El comportamiento de búsqueda es el término que describe cómo el sistema de recursos XAML intenta encontrar un recurso XAML. La búsqueda se produce cuando se hace referencia a una clave como referencia de recursos XAML desde algún lugar del XAML de la aplicación. En primer lugar, el sistema de recursos tiene un comportamiento predecible para donde comprobará la existencia de un recurso en función del ámbito. Si no se encuentra un recurso en el ámbito inicial, el ámbito se expande. El comportamiento de búsqueda continúa en todas las ubicaciones y ámbitos en los que un recurso XAML podría definirse posiblemente por una aplicación o por el sistema. Si todos los intentos de búsqueda de recursos posibles fallan, a menudo se produce un error. Normalmente, es posible eliminar estos errores durante el proceso de desarrollo.

El comportamiento de búsqueda de referencias de recursos XAML comienza con el objeto donde se aplica el uso real y su propia propiedad Resources . Si existe un resourceDictionary de , ResourceDictionary se comprueba para un elemento que tiene la clave solicitada. Este primer nivel de búsqueda rara vez es relevante porque normalmente no se define y, a continuación, se hace referencia a un recurso en el mismo objeto. De hecho, a menudo una propiedad Resources no existe aquí. Puedes hacer referencias a recursos XAML desde casi cualquier lugar en XAML; no estás limitado a las propiedades de las subclases de FrameworkElement.

A continuación, la secuencia de búsqueda comprueba el siguiente objeto primario en el árbol de objetos en tiempo de ejecución de la aplicación. Si existe un frameworkElement.Resources de y contiene un ResourceDictionary, se solicita el elemento de diccionario con la cadena de clave especificada. Si se encuentra el recurso, la secuencia de búsqueda se detiene y el objeto se proporciona a la ubicación donde se realizó la referencia. De lo contrario, el comportamiento de búsqueda avanza al siguiente nivel primario hacia la raíz del árbol de objetos. La búsqueda continúa de forma recursiva hacia arriba hasta que se alcanza el elemento raíz del XAML, lo que agota la búsqueda de todas las ubicaciones de recursos inmediatas posibles.

Nota:

Es una práctica habitual definir todos los recursos inmediatos en el nivel raíz de una página, tanto para aprovechar este comportamiento de búsqueda de recursos como una convención del estilo de marcado XAML.

Si el recurso solicitado no se encuentra en los recursos inmediatos, el siguiente paso de búsqueda es comprobar la propiedad Application.Resources . Application.Resources es el mejor lugar para colocar los recursos específicos de la aplicación a los que hacen referencia varias páginas en la estructura de navegación de la aplicación.

Importante

El orden de los recursos agregados a resourceDictionary afecta al orden en que se aplican. El diccionario XamlControlsResources anula muchas claves de recursos predeterminadas y, por lo tanto, se debe agregar primero a Application.Resources para que no anule otros estilos o recursos personalizados en su aplicación.

Las plantillas de control tienen otra posible ubicación en la búsqueda de referencia: diccionarios de temas. Un diccionario de temas es un único archivo XAML que tiene un elemento ResourceDictionary como raíz. El diccionario de temas podría ser un diccionario fusionado de Application.Resources. El diccionario de temas también puede ser el diccionario de temas específico del control para un control personalizado con plantilla.

Por último, hay una búsqueda entre los recursos de la plataforma. Los recursos de la plataforma incluyen las plantillas de control definidas para cada uno de los temas de la interfaz de usuario del sistema y que definen la apariencia predeterminada de todos los controles que se usan para la interfaz de usuario en una aplicación de Windows Runtime. Los recursos de la plataforma también incluyen un conjunto de recursos con nombre relacionados con la apariencia y los temas del sistema. Estos recursos son técnicamente un elemento MergedDictionaries y, por tanto, están disponibles para la búsqueda desde XAML o código una vez que la aplicación se ha cargado. Por ejemplo, los recursos del tema del sistema incluyen un recurso denominado "SystemColorWindowTextColor" que proporciona una definición de "Color " y "Color" para igualar el color del texto de la aplicación con el color del texto de una ventana del sistema, que está determinado por el sistema operativo y las preferencias del usuario. Otros estilos XAML de la aplicación pueden hacer referencia a este estilo o el código puede obtener un valor de búsqueda de recursos (y convertirlo a Color en el caso de ejemplo).

Para obtener más información y obtener una lista de los recursos específicos del tema y del sistema que están disponibles para una aplicación de Windows que usa XAML, consulta Recursos de temas XAML.

Si la clave solicitada todavía no se encuentra en ninguna de estas ubicaciones, se produce un error o excepción de análisis de XAML. En determinadas circunstancias, la excepción de análisis XAML puede ser una excepción en tiempo de ejecución que no se detecta ni mediante una acción de compilación de marcado XAML ni por un entorno de diseño XAML.

Debido al comportamiento de búsqueda en capas de los diccionarios de recursos, puede definir deliberadamente varios elementos de recursos que cada uno tiene el mismo valor de cadena que la clave, siempre y cuando cada recurso se defina en un nivel diferente. En otras palabras, aunque las claves deben ser únicas dentro de cualquier resourceDictionary determinada, el requisito de unicidad no se extiende a la secuencia de comportamiento de búsqueda en su conjunto. Durante la búsqueda, solo se usa el primer objeto de este tipo que se recupera correctamente para la referencia de recursos XAML y, a continuación, se detiene la búsqueda. Puedes usar este comportamiento para solicitar el mismo recurso XAML por clave en varias posiciones dentro del XAML de la aplicación, pero obtener recursos diferentes, dependiendo del ámbito desde el que se realizó la referencia de recursos XAML y de cómo se comporta esa búsqueda concreta.

Referencias anticipadas dentro de un diccionario de recursos

Las referencias de recursos XAML dentro de un diccionario de recursos determinado deben hacer referencia a un recurso que ya se ha definido con una clave y ese recurso debe aparecer léxicamente antes de la referencia de recursos. Las referencias reenviadas no se pueden resolver mediante una referencia de recursos XAML. Por este motivo, si usas referencias de recursos XAML desde otro recurso, debes diseñar la estructura del diccionario de recursos para que los recursos usados por otros recursos se definan primero en un diccionario de recursos.

Los recursos definidos en el nivel de aplicación no pueden hacer referencias a recursos inmediatos. Esto equivale a intentar una referencia hacia delante, ya que los recursos de la aplicación se procesan primero (cuando se inicia la aplicación por primera vez y antes de cargar cualquier contenido de página de navegación). Sin embargo, cualquier recurso inmediato puede hacer referencia a un recurso de aplicación y esto puede ser una técnica útil para evitar situaciones de referencia directa.

Los recursos XAML deben compartirse

Para que un objeto exista en unresourceDictionary de , ese objeto debe ser .

Es necesario que se pueda compartir porque, cuando se construye y utiliza el árbol de objetos de una aplicación a tiempo de ejecución, los objetos no pueden existir en varias ubicaciones del árbol. Internamente, el sistema de recursos crea copias de valores de recursos que se van a usar en el gráfico de objetos de la aplicación cuando se solicita cada recurso XAML.

A ResourceDictionary y XAML de Windows Runtime en general admiten estos objetos para su uso compartido:

También puede usar tipos personalizados como un recurso que se puede compartir si sigue los patrones de implementación necesarios. Defines estas clases en el código de respaldo (o en componentes en tiempo de ejecución que incluyas) y, a continuación, creas instancias de esas clases en XAML como un recurso. Algunos ejemplos son fuentes de datos de objetos e implementaciones de IValueConverter para la vinculación de datos.

Los tipos personalizados deben tener un constructor predeterminado, ya que es lo que usa un analizador XAML para crear instancias de una clase. Los tipos personalizados que se usan como recursos no pueden tener la clase UIElement en su jerarquía de herencia, porque un UIElement nunca puede ser compartido (siempre está diseñado para representar exactamente un elemento de interfaz de usuario que existe en una posición en el gráfico de objetos de tu aplicación en tiempo de ejecución).

Ámbito de uso de UserControl

Un elemento UserControl tiene una situación especial para el comportamiento de localización de recursos porque incorpora los conceptos inherentes de un ámbito de definición y un ámbito de uso. Un UserControl que hace referencia a un recurso XAML a partir de su ámbito de definición debe ser capaz de admitir la búsqueda de ese recurso dentro de su propia secuencia de búsqueda de ámbito de definición, es decir, no puede acceder a los recursos de la aplicación. Desde el ámbito de uso de un UserControl, una referencia de recursos se considera dentro de la secuencia de búsqueda hacia la raíz de su página de uso (al igual que cualquier otra referencia de recursos realizada a partir de un objeto en un árbol de objetos cargado) y puede acceder a los recursos de la aplicación.

ResourceDictionary y XamlReader.Load

Puedes usar un Diccionario de Recursos ya sea como la raíz o como parte de la entrada XAML para el método XamlReader.Load. También puedes incluir referencias de recursos XAML en ese XAML si todas estas referencias están completamente independientes en el XAML enviado para cargar. XamlReader.Load analiza el XAML en un contexto que no conoce ningún otro objeto ResourceDictionary , ni siquiera Application.Resources. Además, no uses {ThemeResource} desde XAML enviado a XamlReader.Load.

Uso de ResourceDictionary desde código

La mayoría de los escenarios de un resourceDictionary de se controlan exclusivamente en XAML. Declaras el recurso ResourceDictionary como contenedor y los recursos dentro de él como un archivo XAML o un conjunto de nodos XAML en un archivo de definición de interfaz de usuario. Y, a continuación, usas referencias de recursos XAML para solicitar esos recursos de otras partes de XAML. Aun así, hay ciertos escenarios en los que es posible que la aplicación quiera ajustar el contenido de un ResourceDictionary mediante código que se ejecuta mientras se ejecuta la aplicación, o al menos para consultar el contenido de un ResourceDictionary para ver si un recurso ya está definido. Estas llamadas de código se realizan en una instancia de ResourceDictionary, por lo que primero debe recuperar una, ya sea un ResourceDictionary inmediato en algún lugar del árbol de objetos obteniendo FrameworkElement.Resources, o Application.Current.Resources.

En el código de C# o Microsoft Visual Basic, puede hacer referencia a un recurso de un ResourceDictionary mediante el indexador (Item). ResourceDictionary es un diccionario con clave de cadena, por lo que el indexador usa la clave de cadena en lugar de un índice entero. En código de extensiones de componentes de Visual C++ (C++/CX), use Búsqueda.

Cuando se usa código para examinar o cambiar un ResourceDictionary, el comportamiento de las API como Lookup o Item no atraviesa de recursos inmediatos a recursos de la aplicación; es un comportamiento del analizador XAML que solo se produce a medida que se cargan las páginas XAML. En tiempo de ejecución, el ámbito de las claves se limita a la instancia de ResourceDictionary que está usando en ese momento. Sin embargo, ese ámbito se extiende a MergedDictionaries.

Además, si solicita una clave que no existe en ResourceDictionary, puede que no haya un error; el valor devuelto puede proporcionarse simplemente como null. Sin embargo, es posible que se produzca un error si intenta usar el valor NULL devuelto como un valor. El error provendría del setter de la propiedad, no de la llamada de ResourceDictionary. La única manera de evitar un error es si la propiedad aceptara null como un valor válido. Ten en cuenta cómo este comportamiento contrasta con el comportamiento de búsqueda de XAML en tiempo de análisis de XAML. Un error al resolver la clave proporcionada de XAML en tiempo de análisis produce un error de análisis de XAML, incluso si la propiedad podría haber aceptado nulo.

Los diccionarios de recursos combinados se incluyen en el ámbito de índice del diccionario de recursos principal que hace referencia al diccionario combinado en tiempo de ejecución. En otras palabras, puede usar elemento o Lookup del diccionario principal para buscar los objetos que realmente se definieron en el diccionario combinado. En este caso, el comportamiento de búsqueda se parece al comportamiento de búsqueda XAML en tiempo de análisis: si hay varios objetos en diccionarios combinados que cada uno tiene la misma clave, se devuelve el objeto del último diccionario agregado.

Puede agregar elementos a un ResourceDictionary de existente llamando a Agregar (C# o Visual Basic) o Insertar (C++/CX). Puede agregar los elementos a los recursos inmediatos o a los recursos de la aplicación. Cualquiera de estas llamadas API requiere una clave, que satisface el requisito de que cada elemento de un ResourceDictionary tenga una clave. Sin embargo, los elementos que agregas a resourceDictionary en tiempo de ejecución no son relevantes para las referencias de recursos XAML. La búsqueda necesaria para las referencias a recursos XAML se produce cuando se analiza por primera vez XAML a medida que se carga la aplicación (o se detecta un cambio de tema). Los recursos agregados a las colecciones en tiempo de ejecución no estaban disponibles y modificar ResourceDictionary no invalida un recurso ya recuperado de él aunque cambie el valor de ese recurso.

También puede quitar elementos de resourceDictionary en tiempo de ejecución, realizar copias de algunos o todos los elementos u otras operaciones. La lista de miembros de ResourceDictionary indica qué API están disponibles. Tenga en cuenta que, dado que ResourceDictionary tiene una API proyectada para admitir sus interfaces de colección subyacentes, las opciones de API difieren en función de si usa C# o Visual Basic frente a C++/CX.

ResourceDictionary y localización

Un resourceDictionary XAML puede contener inicialmente cadenas que se van a localizar. Si es así, almacene estas cadenas como recursos de proyecto en lugar de en resourceDictionary. Quita las cadenas del XAML y, en su lugar, asigna al elemento propietario una directiva x:Uid con el valor . A continuación, defina un recurso en un archivo de recursos. Proporcione un nombre de recurso con el formato XUIDValue. PropertyName y un valor de recurso de la cadena que se debe localizar.

Búsqueda de recursos personalizados

En escenarios avanzados, puedes implementar una clase que pueda tener un comportamiento diferente al comportamiento de búsqueda de referencia de recursos XAML descrito en este tema. Para ello, implemente la clase CustomXamlResourceLoadery, a continuación, puede acceder a ese comportamiento mediante la extensión de marcado CustomResource para las referencias de recursos, en lugar de usar StaticResource o ThemeResource. La mayoría de las aplicaciones no tendrán escenarios que requieran esto. Para obtener más información, consulta CustomXamlResourceLoader.

  • Last updated on