ResourceDictionary Classe

Référence

Définition

Espace de noms:: Windows.UI.Xaml

Important

Certaines informations portent sur la préversion du produit qui est susceptible d’être en grande partie modifiée avant sa publication. Microsoft exclut toute garantie, expresse ou implicite, concernant les informations fournies ici.

Modifier

Définit un référentiel pour les ressources XAML, telles que les styles, que votre application utilise. Vous définissez les ressources en XAML et vous pouvez ensuite les récupérer en XAML à l’aide de l’extension de balisage {StaticResource} et de l’extension de balisage {ThemeResource} . Vous pouvez également accéder aux ressources avec du code, mais c’est moins courant.

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

Héritage: Object IInspectable DependencyObject ResourceDictionary

Dérivé: Windows.UI.Xaml.ColorPaletteResources

Attributs: ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Implémente: IDictionary<Object,Object> IMap<IInspectable,IInspectable> IIterable<IKeyValuePair<K,V>> IEnumerable<KeyValuePair<K,V>> IEnumerable<KeyValuePair<Object,Object>> IIterable<IKeyValuePair<IInspectable,IInspectable>>

Configuration requise pour Windows

Famille d’appareils	Windows 10 (introduit dans 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (introduit dans v1.0)

Remarques

Un dictionnaire de ressources est un référentiel pour les ressources XAML, telles que les styles, que votre application utilise. Vous définissez les ressources en XAML et pouvez ensuite les récupérer en XAML à l’aide de l’extension de balisage {StaticResource} et de l’extension de balisage {ThemeResource} . Vous pouvez également accéder aux ressources avec du code, mais c’est moins courant. Vous pouvez utiliser des ressources pour faire en sorte que certaines valeurs telles que les couleurs de pinceau ou les mesures de pixels soient utilisées de manière cohérente dans toute votre application. Pour plus d’informations sur l’utilisation efficace des dictionnaires de ressources, consultez ResourceDictionary et références aux ressources XAML.

Utilisations des éléments ResourceDictionary

Le type ResourceDictionary est utilisé comme valeur de deux propriétés, FrameworkElement.Resources et Application.Resources, qui sont importantes pour la structure globale d’une application UWP. Les fichiers XAML que vous obtenez à partir d’un modèle de projet de démarrage pour une application commencent par les valeurs initiales pour FrameworkElement.Resources, et le fichier app.xaml peut commencer par des valeurs initiales pour Application.Resources. Les ressources exactes qui y sont définies dépendent du modèle de démarrage de projet que vous utilisez.

Ce code XAML montre l’utilisation d’une propriété FrameworkElement.Resources . Dans ce cas, frameworkElement est une page. Il n’existe aucun élément ResourceDictionary subordonné à l’élément de propriété Page.Resources, mais sa présence est implicite ; Pour plus d’informations, consultez la section « Remarques sur la syntaxe XAML » ci-dessous. Le code XAML place un style dans ResourceDictionary avec une valeur d’attribut x :Key « TextBlockStyle1 ». Plus bas dans le code XAML, l’extension de balisage {StaticResource} fait référence au style dans le dictionnaire de ressources pour fournir une valeur à la propriété Style de l’élément TextBlock .

Le style tel qu’indiqué n’applique pas réellement de style à TextBlock, mais vous pouvez ajouter des propriétés Style dans Microsoft Visual Studio. Vous pouvez ensuite utiliser la ressource Style aussi souvent que vous le souhaitez sur la page pour appliquer l’uniformité.

Vous pouvez utiliser Microsoft Visual Studio pour créer des dictionnaires de ressources. Cet exemple a été créé en procédant comme suit : placez un TextBlock sur l’aire de conception, cliquez avec le bouton droit, choisissez Modifier le style/ Créer vide, puis « Ce document » pour définir la nouvelle ressource dans 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>

Ce code XAML, à partir du fichier AppPage.xaml de l’exemple AtomPub, montre l’utilisation d’une propriété Application.Resources . Le code XAML place deux éléments Style dans le dictionnaire de ressources, ce qui les rend disponibles dans l’ensemble de l’application.

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

Ce code XAML du fichier MainPage.xaml utilise l’extension de balisage {StaticResource} pour accéder aux styles TitleStyle et 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>
 ...

Vous pouvez factoriser des ressources dans leur propre fichier XAML en utilisant ResourceDictionary comme élément racine du fichier. Vous pouvez ensuite inclure ces ressources dans un dictionnaire de ressources FrameworkElement.Resources ou Application.Resources . Pour ce faire, vous utilisez la propriété ResourceDictionary.MergedDictionaries ou la propriété ResourceDictionary.ThemeDictionaries de l’élément ResourceDictionary.

Ce fichier, Common/Styles1.xaml, définit les ressources Style à l’aide de ResourceDictionary comme élément racine :

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

Supposons maintenant qu’il existe un autre fichier, Common/Styles2.xaml, qui définit de la même façon les ressources Style . Ce code XAML montre comment fusionner les ressources de ces deux fichiers à l’aide de la propriété ResourceDictionary.MergedDictionaries pour créer un dictionnaire de ressources Application.Resources . Le CODE XAML définit également deux ressources style supplémentaires et les fusionne avec les ressources des deux fichiers.

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

Pour plus d’informations sur la façon dont les ressources de dictionnaire fusionné sont résolues, consultez la section « Dictionnaires de ressources fusionnés » dans Références de ressources ResourceDictionary et XAML.

Propriété x :Key

En XAML, les clés des resourceDictionaryitems sont déclarées en définissant l’attribut x :Keysur les éléments qui représentent les ressources XAML. En règle générale, si vous essayez de placer un élément enfant qui n’a pas de valeur de clé dans un ResourceDictionary, une exception d’analyse XAML ou une exception Windows Runtimeexception est levée. La condition d’exception peut également être notée comme un avertissement par les surfaces de conception XAML. Toutefois, il existe trois cas notables où un élément ResourceDictionarychild ne nécessite pas de valeur d’attribut x :Key:

Une ressource Style peut utiliser sa valeur TargetType comme clé de ressource implicite. Pour plus d’informations sur le fonctionnement des clés implicites pour les styles et les modèles de contrôle, consultez Contrôles de style.
Les éléments ResourceDictionary avec des valeurs Source qui représentent des valeurs ResourceDictionary.MergedDictionaries ne peuvent pas avoir d’attribut x :Key sur ResourceDictionary. Dans chaque fichier de dictionnaire fusionné (celui référencé par URI comme source), vous avez besoin de clés pour chaque ressource.
L’attribut x :Name peut être utilisé à la place de l’attribut x :Key, pour des raisons héritées. Toutefois, l’attribut x :Name en lui-même n’active pas la recherche de ressource XAML de cet élément. La convention d’identification de l’attribut x :Name est utilisée pour certains scénarios, tels que la définition d’animations de table de montage séquentiel. Pour plus d’informations, consultez attribut x :Name.

Itération via un ResourceDictionary

Vous pouvez itérer via un ResourceDictionary en C# ou Microsoft Visual Basic. Dans de nombreux cas, comme l’utilisation de la syntaxe foreach , le compilateur effectue ce cast pour vous et vous n’aurez pas besoin d’effectuer un cast IEnumerable vers explicitement. Si vous avez besoin d’un cast explicite, par exemple si vous souhaitez appeler GetEnumerator, castez en IEnumerable<T> avec une contrainte KeyValuePair<Object> .

ResourceDictionary et Microsoft Visual Studio

Microsoft Visual Studio fournit un choix de page Ajouter un nouvel élément pour un dictionnaire de ressources. Utilisez cette option chaque fois que vous souhaitez définir un nouveau dictionnaire de ressources XAML libre, par exemple pour servir de source pour un dictionnaire fusionné. Microsoft Visual Studio ajoute également un dictionnaire de ressources XAML libre au projet chaque fois que vous utilisez Ajouter un nouvel élément pour créer un contrôle avec modèle. Ce dictionnaire de ressources fournit les modèles de thème par défaut. Microsoft Visual Studio peut créer un ResourceDictionary pour vous dans votre code XAML si vous modifiez des copies de styles ou de modèles et qu’un ResourceDictionary pour l’emplacement de ressource choisi (application, page ou autonome) n’existe pas encore.

Remarques sur la syntaxe XAML

Notez que la syntaxe de collection implicite XAML pour ResourceDictionary n’inclut pas d’élément d’objet pour ResourceDictionary. Il s’agit d’un exemple de syntaxe de collection implicite XAML ; une balise représentant l’élément de collection peut être omise. Les éléments ajoutés en tant qu’éléments à la collection sont spécifiés en tant qu’éléments enfants d’un élément de propriété d’une propriété dont le type sous-jacent prend en charge une méthode Add de dictionnaire/mappage.

Pour un dictionnaire de ressources fusionné, vous devez déclarer explicitement un élément objet ResourceDictionary, afin de pouvoir également déclarer l’élément de propriété ResourceDictionary.MergedDictionaries et Source. Par conséquent, il y a au moins deux éléments d’objet ResourceDictionary impliqués, et vous utilisez cette syntaxe.

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

Dans cette syntaxe, le ResourceDictionary externe est le ResourceDictionary principal. Le ResourceDictionary interne est le ResourceDictionary en cours de fusion.

Pour l’utilisation de la collection implicite, l’espace réservé approprié pour la propriété FrameworkElement.Resources s’affiche. Vous pouvez également utiliser cette utilisation de collection implicite pour la propriété Application.Resources , ou éventuellement pour une propriété personnalisée qui utilise ResourceDictionary comme type de propriété.

Types partageables et types UIElement

Un dictionnaire de ressources est une technique permettant de définir des types et des valeurs partageables de ces types en XAML. Tous les types ou valeurs ne conviennent pas à l’utilisation à partir d’un ResourceDictionary. Parmi les types où le partage est pris en charge, citons Style, toute sous-classe FrameworkTemplate , les types de données intrinsèques XAML, les pinceaux, les couleurs et les transformations. Pour plus d’informations sur les types considérés comme partageables, consultez ResourceDictionary et références de ressources XAML. En règle générale, les types dérivés d’UIElement ne sont pas partageables, sauf s’ils proviennent de modèles et de l’application d’un modèle sur un instance de contrôle spécifique. À l’exception du cas de modèle, un UIElement est censé exister à un seul emplacement dans une arborescence d’objets après son instanciation, et le fait qu’un UIElement soit partageable violerait potentiellement ce principe.

Dans la pratique, la grande majorité des ressources définies dans un ResourceDictionary sera l’une des suivantes :

Modèles de contrôle pour un contrôle, y compris ses états visuels.
Styles de prise en charge pour des parties de contrôles
Styles pour les éléments qui font partie de l’interface utilisateur d’application classique, mais qui ne sont pas des contrôles, comme TextBlock
Modèles de données pour les contrôles et les panneaux qui utilisent la liaison de données
Valeurs brush spécifiques, principalement SolidColorBrush
Chaînes ou autres constantes qui n’ont jamais besoin d’être localisées (les chaînes et constantes qui doivent être localisées ne doivent pas être dans un ResourceDictionary ; pour plus d’informations, voir Démarrage rapide : Traduction de ressources d’interface utilisateur)

Accès à un objet ResourceDictionary dans le code

L’API que votre code utilise pour accéder aux ressources dans un ResourceDictionary dépend du langage de programmation que vous utilisez :

Pour C# ou Microsoft Visual Basic, vous utilisez l’API qui implémente IDictionary<TKey, TValue> et IEnumerable<T>. Par exemple, TryGetValue ou l’indexeur Item .
Pour les extensions de composant Visual C++ (C++/CX), vous utilisez l’API qui implémente IMap<K,V> et IIterable. Par exemple, Recherche.
Les API qui ne font pas partie de la prise en charge de la collection, comme Source, sont les mêmes dans toutes les langues.

Pour plus d’informations sur l’utilisation de ResourceDictionary dans le code, consultez la section « Utilisation d’un ResourceDictionary à partir du code » dans ResourceDictionary et références de ressources XAML.

Ressources système

Certaines ressources de thème référencent des valeurs de ressource système comme sous-valeur sous-jacente. Une ressource système est une valeur de ressource spéciale qui ne se trouve dans aucun dictionnaire de ressource XAML. Ces valeurs dépendent du XAML Windows Runtime, qui prend en charge le transfert de valeurs à partir du système proprement dit, ainsi que leur représentation sous une forme qu’une ressource XAML peut référencer.

Remarques pour les versions précédentes

Optimisation du chargement des ressources dans Windows 8.1

À compter de Windows 8.1, il existe une optimisation du chargement des ressources activée par le modèle d’application et l’analyseur XAML Windows Runtime. Par Windows 8, l’analyseur XAML a chargé des ressources à partir de app.xaml et a créé chacune d’entre elles en tant qu’objets dans le cadre du démarrage. Ce n’était pas très efficace s’il y avait de grands dictionnaires là-bas. De plus, ces ressources comprenaient les éléments nécessaires aux trois thèmes, et deux des trois thèmes ne seraient même pas actifs. À compter de Windows 8.1, l’analyseur XAML crée les ressources uniquement lorsqu’elles sont spécifiquement demandées. La demande peut provenir d’autres ressources ou de XAML d’application ou de page au fur et à mesure que chacune d’elles est chargée. Ce comportement de l’analyseur réduit le temps nécessaire pour lire le dictionnaire au niveau de l’application au démarrage et permet à la première page d’application de se charger plus rapidement dans la plupart des cas. Les ressources nécessaires à d’autres thèmes actuellement inactifs ne sont chargées que si ce thème est choisi pour devenir le thème actif par l’utilisateur. À ce moment-là, toute ressource dans laquelle l’extension de balisage {ThemeResource} a été utilisée pour la requête est recalculée en fonction du thème nouvellement actif.

Comportement de Windows 8

Windows 8 n’avait pas les optimisations décrites ci-dessus. Le ResourceDictionary pour Application.Resources devait terminer l’analyse avant qu’une page autre que l’écran de démarrage puisse se charger dans la fenêtre de l’application. Pour cette raison, vous pouvez voir des différences dans le moment où vous reciblez votre application pour Windows 8.1. L’application doit se charger plus rapidement, mais il peut ne pas être possible d’isoler cette amélioration par rapport aux autres modifications que vous avez apportées au code de votre application dans le cadre du reciblage. Certains des endroits où vous pouvez voir des preuves de changements de minutage en raison du chargement optimisé des ressources incluent lorsque les constructeurs sont appelés par l’analyseur, pour des objets tels que des objets Application , des convertisseurs ou d’autres classes personnalisées. Les applications qui ont été compilées pour Windows 8, mais qui sont exécutées dans Windows 8.1, continuent d’appliquer le comportement Windows 8.

Pour plus d’informations sur les performances et la factoring des ressources XAML, consultez Optimiser votre balisage XAML.

Constructeurs

ResourceDictionary()

Initialise une nouvelle instance de la classe ResourceDictionary.

Propriétés

Dispatcher	Obtient le CoreDispatcher auquel cet objet est associé. CoreDispatcher représente une fonctionnalité qui peut accéder à DependencyObject sur le thread d’interface utilisateur, même si le code est initié par un thread autre que l’interface utilisateur. (Hérité de DependencyObject)
MergedDictionaries	Obtient une collection des dictionnaires ResourceDictionary qui constituent les différents dictionnaires de ressources dans les dictionnaires fusionnés.
Size	Obtient le nombre d’éléments contenus dans la collection.
Source	Obtient ou définit un URI (Uniform Resource Identifier) qui fournit l’emplacement source d’un dictionnaire de ressources fusionné.
ThemeDictionaries	Obtient une collection de dictionnaires de ressources fusionnés qui sont spécifiquement keyisés et composés pour répondre aux scénarios de thème, par exemple en fournissant des valeurs de thème pour « HighContrast ».

Méthodes

Clear()	Supprime tous les éléments de ce ResourceDictionary.
ClearValue(DependencyProperty)	Efface la valeur locale d’une propriété de dépendance. (Hérité de DependencyObject)
First()	Retourne un itérateur pour les éléments de la collection.
GetAnimationBaseValue(DependencyProperty)	Retourne toute valeur de base établie pour une propriété de dépendance, qui s’appliquerait dans les cas où une animation n’est pas active. (Hérité de DependencyObject)
GetValue(DependencyProperty)	Retourne la valeur effective actuelle d’une propriété de dépendance à partir d’un DependencyObject. (Hérité de DependencyObject)
GetView()	Récupère une vue par rapport à ResourceDictionary.
HasKey(Object)	Retourne si le ResourceDictionary a une entrée avec la clé demandée.
Insert(Object, Object)	Ajoute une nouvelle entrée à ResourceDictionary.
Lookup(Object)	Retourne la valeur de la clé demandée, si une entrée avec cette clé existe.
ReadLocalValue(DependencyProperty)	Retourne la valeur locale d’une propriété de dépendance, si une valeur locale est définie. (Hérité de DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	Inscrit une fonction de notification pour écouter les modifications apportées à un DependencyProperty spécifique sur ce instance DependencyObject. (Hérité de DependencyObject)
Remove(Object)	Supprime un élément spécifique du ResourceDictionary.
SetValue(DependencyProperty, Object)	Définit la valeur locale d’une propriété de dépendance sur un DependencyObject. (Hérité de DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	Annule une notification de modification précédemment inscrite en appelant RegisterPropertyChangedCallback. (Hérité de DependencyObject)

S’applique à