x:Key, directive

Identifie de façon unique les éléments qui sont créés et référencés dans un dictionnaire défini en XAML. L’ajout d’une x:Key valeur à un élément objet XAML est le moyen le plus courant d’identifier une ressource dans un dictionnaire de ressources, par exemple dans un WPF ResourceDictionary .

Utilisation d'attributs XAML

<object x:Key="stringKeyValue".../>  
-or-  
<object x:Key="{markupExtensionUsage}".../>  

Utilisation d’attributs XAML (spécifique à WPF)

<object.Resources>  
  <object x:Key="stringKeyValue".../>  
</object.Resources>  
-or-  
<object.Resources>  
  <object x:Key="{markupExtensionUsage}".../>  
</object.Resources>  

Valeurs XAML

Valeur Description
stringKeyValue Chaîne de texte à utiliser comme clé. La chaîne de texte doit être conforme à la syntaxe XamlName.
markupExtensionUsage Dans les délimiteurs {} d’extension de balisage, il s’agit d’une utilisation d’extension de balisage qui fournit un objet à utiliser comme clé. Consultez la section Notes.

Remarques

x:Key prend en charge le concept de dictionnaire de ressources XAML. XAML en tant que langage ne définit pas une implémentation de dictionnaire de ressources, qui est conservée dans des infrastructures d’interface utilisateur spécifiques. Pour en savoir plus sur la façon dont les dictionnaires de ressources XAML sont implémentés dans WPF, consultez vue d’ensemble des ressources XAML (WPF .net).

Dans XAML 2006 et WPF, x:Key doit être fourni en tant qu’attribut. Vous pouvez toujours utiliser des clés qui ne sont pas des chaînes, mais cela nécessite une utilisation d’extension de balisage afin de fournir la valeur de non-chaîne sous forme d’attribut. Si vous utilisez XAML 2009, x:Key peut être spécifié comme un élément, pour prendre en charge explicitement des dictionnaires indexés par des types d’objets autres que des chaînes sans nécessiter d’extension de balisage intermédiaire. Consultez la section « XAML 2009 » dans cette rubrique. Le reste de la section Remarques s’applique spécifiquement à l’implémentation XAML 2006.

La valeur d’attribut de x:Key peut être n’importe quelle chaîne définie dans la grammaire XamlName ou peut être un objet évalué par le biais d’une extension de balisage. Consultez « Remarques sur l’utilisation de WPF » pour obtenir un exemple de WPF.

Les éléments enfants d’un élément parent qui est une IDictionary implémentation doivent généralement inclure un x:Key attribut qui spécifie une valeur de clé unique dans ce dictionnaire. Les infrastructures peuvent implémenter des propriétés de clé avec alias pour remplacer x:Key sur des types particuliers ; les types qui définissent de telles propriétés doivent être attribués avec DictionaryKeyPropertyAttribute .

Le code équivalent à la spécification x:Key est la clé utilisée pour le sous-jacent IDictionary . Par exemple, un x:Key qui est appliqué dans le balisage pour une ressource dans WPF est équivalent à la valeur key du paramètre de ResourceDictionary.Add lorsque vous ajoutez la ressource à un WPF ResourceDictionary dans le code.

Remarques sur l'utilisation de WPF

Les objets enfants d’un objet parent qui est une IDictionary implémentation, tels que WPF ResourceDictionary , doivent généralement inclure un x:Key attribut, et la valeur de clé doit être unique dans ce dictionnaire. Il existe deux exceptions notables :

  • Certains types WPF déclarent une clé implicite pour l’utilisation de dictionnaire. Par exemple, un Style avec un TargetType , ou un DataTemplate avec un DataType , peut être dans un ResourceDictionary et utiliser la clé implicite.

  • WPF prend en charge un concept de dictionnaire de ressources fusionné. Les clés peuvent être partagées entre les dictionnaires fusionnés, et le comportement de la clé partagée est accessible à l’aide FindResource de. Pour plus d’informations, consultez dictionnaires de ressources fusionnés.

Dans l’implémentation générale et le modèle d’application XAML WPF, l’unicité de la clé n’est pas vérifiée par le compilateur de balisage XAML. Au lieu de cela, les valeurs manquantes ou non uniques x:Key provoquent des erreurs de l’analyseur XAML au moment du chargement. toutefois, Visual Studio la gestion des dictionnaires pour WPF peut souvent noter de telles erreurs dans la phase de conception.

Notez que dans la syntaxe indiquée, l' ResourceDictionary objet est implicite dans la manière dont le processeur XAML WPF produit une collection pour remplir une Resources collection. Un ResourceDictionary n’est généralement pas fourni explicitement comme un élément dans le balisage, bien qu’il puisse être dans certains cas, s’il le souhaite, à des fins de clarté (il s’agit d’un élément objet de collection entre l' Resources élément de propriété et les éléments dans qui remplissent le dictionnaire). Pour plus d’informations sur la raison pour laquelle un objet de collection est presque toujours un élément implicite dans le balisage, consultez syntaxe XAML en détail.

Dans l’implémentation XAML WPF, la gestion des clés de dictionnaire de ressources est définie par la ResourceKey classe abstraite. Toutefois, le processeur XAML WPF produit des types d’extension sous-jacents différents pour les clés en fonction de leurs utilisations. Par exemple, la clé d’une classe ou d’une DataTemplate classe dérivée est gérée séparément et produit un objet distinct DataTemplateKey .

Les clés et les noms utilisent des directives et des éléments de langage différents ( x:Key par rapport x:Name à) dans la définition XAML de base. Les clés et les noms sont également utilisés dans différentes situations par la définition WPF et l’application de ces concepts. Pour plus d’informations, consultez portées de code XAML WPF.

Comme indiqué précédemment, la valeur d’une clé peut être fournie par le biais d’une extension de balisage et peut être différente d’une valeur de chaîne. Un exemple de scénario WPF est que la valeur de x:Key peut être un ComponentResourceKey. Certains contrôles exposent une clé de style de ce type pour une ressource de style personnalisée qui influence une partie de l’apparence et du comportement de ce contrôle sans remplacer totalement le style. Un exemple d’une telle clé est ButtonStyleKey .

La fonctionnalité de dictionnaire fusionné WPF introduit des considérations supplémentaires pour l’unicité des clés et le comportement de recherche de clé. Pour plus d’informations, consultez dictionnaires de ressources fusionnés.

XAML 2009

XAML 2009 assouplit la restriction qui x:Key est toujours fournie sous forme d’attribut.

Dans WPF, vous pouvez utiliser les fonctionnalités XAML 2009, mais uniquement pour le code XAML qui n’est pas compilé par balisage. Le code XAML compilé par balisage pour WPF et la forme BAML du code XAML ne prennent actuellement pas en charge les mots clés et les fonctionnalités XAML 2009.

Sous XAML 2009, vous pouvez spécifier x:Key des éléments par le biais de l’utilisation suivante :

Utilisation des éléments XAML (XAML 2009 uniquement)

<object>  
  <x:Key>  
keyObject  
  </x:Key>  
...  
</object>  

Valeurs XAML

Valeur Description
keyObject Élément objet pour l’objet qui est utilisé comme clé pour un donné object dans un dictionnaire spécialisé.
  • Le conteneur/parent de ce type d’utilisation n’est pas indiqué ici. object est supposé être un enfant d’un élément objet qui représente une implémentation de dictionnaire spécialisée. keyObject est supposé être une instance d’objet (ou une valeur d’un type valeur) qui est appropriée comme clé pour cette implémentation de dictionnaire spécialisé particulière.

  • WPF n’implémente pas les dictionnaires qui requièrent cette utilisation. Les clés d’objet sont plus une fonctionnalité générale du langage XAML, qui peut s’avérer utile pour certains scénarios de dictionnaires personnalisés où la création du dictionnaire en XAML est souhaitable. Pour les fonctionnalités WPF telles que les styles implicites qui utilisent des clés de non-chaîne pour les ressources, d’autres techniques permettant d’établir ou de spécifier les clés existent, l’utilisation d’une clé d’objet n’est donc pas nécessaire.

  • keyObject peut également être une utilisation d’extension de balisage dans un formulaire d’élément objet, plutôt qu’une instance d’objet directe.

Remarques sur l’utilisation de Silverlight

x:Key pour Silverlight est documenté séparément. Pour plus d’informations, consultez espace de noms XAML (x :) Fonctionnalités de langage (Silverlight).

Voir aussi