ResourceDictionary Classe

Référence

Définition

Espace de noms:: Microsoft.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 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(Microsoft.UI.Xaml.WinUIContract, 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(Microsoft.UI.Xaml.WinUIContract), 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é: Microsoft.UI.Xaml.ColorPaletteResources

Microsoft.UI.Xaml.Controls.XamlControlsResources

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

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 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. 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 ResourceDictionary type est utilisé comme valeur de deux propriétés, FrameworkElement.Resources et Application.Resources, qui sont importantes pour la structure globale d’une application SDK d'application Windows. 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 ResourceDictionary élément subordonné à l’élément Page.Resources property, 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 avec la ResourceDictionary valeur d’attribut x:Key « TextBlockStyle1 ». Plus bas dans le XAML, l’extension de balisage {StaticResource} fait référence Style au 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 Style des propriétés dans Microsoft Visual Studio. Vous pouvez ensuite utiliser la Style ressource aussi souvent que vous le souhaitez sur la page pour appliquer l’uniformité.

<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 en utilisant 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 ResourceDictionary éléments 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, cela lève une exception d’analyse XAML ou une exception Windows Runtime. 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 ResourceDictionary élément enfant 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 ResourceDictionary éléments 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 au sein d’un ResourceDictionary en C#. Dans de nombreux cas, comme l’utilisation foreach de la syntaxe, le compilateur effectue ce cast pour vous et vous n’aurez pas besoin de le faire IEnumerable explicitement. Si vous devez effectuer un cast explicite, par exemple si vous souhaitez appeler GetEnumerator, effectuez un cast en IEnumerable avec une KeyValuePair<Object,Object> contrainte.

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 nouveau 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 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 ResourceDictionary élément objet, 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 ResourceDictionary éléments d’objet impliqués, et vous utilisez cette syntaxe.

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

Dans cette syntaxe, l’externe ResourceDictionary est le principal ResourceDictionary. L’interne ResourceDictionary 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 potentiellement 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 sera l’une ResourceDictionary 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#, vous utilisez l’API qui implémente IDictionary<TKey, TValue> et IEnumerable. Par exemple, TryGetValue ou l’indexeur Item .
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 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.

Constructeurs

ResourceDictionary()

Initialise une nouvelle instance de la classe ResourceDictionary.

Propriétés

Dispatcher	Retourne `null` toujours dans une application SDK d'application Windows. Utilisez DispatcherQueue à la place. (Hérité de DependencyObject)
DispatcherQueue	Obtient le `DispatcherQueue` auquel cet objet est associé. représente `DispatcherQueue` une fonctionnalité qui peut accéder au `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 à

Share via