Partager via

x :Key, directive

  • Article

Identifie de manière unique les éléments créés et référencés dans un dictionnaire défini par XAML. L’ajout d’une valeur x:Key à un élément d’objet XAML est le moyen le plus courant d’identifier une ressource dans un dictionnaire de ressources, par exemple dans un ResourceDictionaryWPF.

Utilisation des attributs XAML

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

Utilisation de l’attribut 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 à lade grammaire XamlName .
markupExtensionUsage Dans les délimiteurs d’extension de balisage {}, une utilisation de l’extension de balisage qui fournit un objet à utiliser comme clé. Voir les remarques.

Remarques

x:Key prend en charge le concept de dictionnaire de ressources XAML. XAML en tant que langage ne définit pas d’implémentation de dictionnaire de ressources, qui est laissée à des frameworks 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 non chaînes, mais cela nécessite une utilisation de l’extension de balisage afin de fournir la valeur non chaîne sous forme d’attribut. Si vous utilisez XAML 2009, x:Key pouvez être spécifié en tant qu’élément pour prendre en charge explicitement les dictionnaires clés par types d’objets autres que les chaînes sans nécessiter d’extension de balisage intermédiaire. Consultez la section « XAML 2009 » de cette rubrique. Le reste de la section Notes s’applique spécifiquement à l’implémentation XAML 2006.

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

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

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

Notes d’utilisation WPF

Les objets enfants d’un objet parent qui est une implémentation IDictionary, comme le ResourceDictionaryWPF, doivent généralement inclure un attribut x:Key, 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 du dictionnaire. Par exemple, un Style avec un TargetType, ou un DataTemplate avec un DataType, peut se trouver 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 clé partagée est accessible à l’aide de FindResource. Pour plus d’informations, consultez dictionnaires de ressources fusionnés.

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

Notez que dans la syntaxe indiquée, l’objet ResourceDictionary est implicite dans la façon dont le processeur XAML WPF produit une collection pour remplir une collection Resources collection. Une ResourceDictionary n’est généralement pas fournie explicitement en tant qu’élément dans le balisage, bien qu’elle puisse être dans certains cas si elle était souhaitée pour plus de clarté (il s’agirait d’un élément objet de collection entre l’élément de propriété Resources et les éléments dans remplit 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 classe abstraite ResourceKey. Toutefois, le processeur XAML WPF produit différents types d’extensions sous-jacents pour les clés en fonction de leurs utilisations. Par exemple, la clé d’un DataTemplate ou d’une classe dérivée est gérée séparément et produit un objet DataTemplateKey distinct.

Les clés et les noms utilisent différentes directives et éléments de langage (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 noms XAML WPF.

Comme indiqué précédemment, la valeur d’une clé peut être fournie via une extension de balisage et peut être autre qu’une valeur de chaîne. Un exemple de scénario WPF est que la valeur de x:Key peut être une 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 de telle clé est ButtonStyleKey.

La fonctionnalité de dictionnaire fusionné WPF introduit des considérations supplémentaires pour l’unicité clé 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 toujours être fournie sous forme d’attribut.

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

Sous XAML 2009, vous pouvez spécifier x:Key éléments via 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 de l’objet utilisé comme clé pour un object donné dans un dictionnaire spécialisé.

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

  • WPF n’implémente pas de dictionnaires qui nécessitent cette utilisation. Les clés d’objet sont plus une fonctionnalité générale du langage XAML, éventuellement utile pour certains scénarios de dictionnaire personnalisé 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 non-chaînes pour les ressources, d’autres techniques d’établissement ou de spécification des clés existent, de sorte que l’utilisation d’une clé d’objet n’est pas nécessaire.

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

Notes d’utilisation silverlight

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

Voir aussi