x:Key, directivex:Key Directive

Identifie uniquement les éléments qui sont créés et référencés dans un dictionnaire défini en XAML.Uniquely identifies elements that are created and referenced in a XAML-defined dictionary. L'ajout d'une valeur x:Key à un élément d'objet XAML est la méthode la plus courante pour identifier une ressource dans un dictionnaire de ressources, par exemple dans un WPF ResourceDictionary.Adding an x:Key value to a XAML object element is the most common way to identify a resource in a resource dictionary, for example in a WPF ResourceDictionary.

Utilisation des attributs XAMLXAML Attribute Usage

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

Utilisation des attributs XAML (spécifique à WPF)XAML Attribute Usage (WPF-specific)

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

Valeurs XAMLXAML Values

stringKeyValue Chaîne de texte à utiliser comme une clé.A text string to use as a key. La chaîne de texte doit être conforme à la syntaxe XamlName.The text string must conform to the XamlName Grammar.
markupExtensionUsage Dans les délimiteurs d’extension de balisage {}, une utilisation d’extension de balisage qui fournit un objet à utiliser comme clé.Within the markup extension delimiters {}, a markup extension usage that provides an object to use as a key. Consultez la section Notes.See Remarks.

NotesRemarks

x:Key prend en charge le concept de dictionnaire de ressources XAML.x:Key supports the XAML resource dictionary concept. XAML en tant que langage ne définit pas une implémentation du dictionnaire des ressources, qui est laissée aux infrastructures d'interface utilisateur spécifiques.XAML as a language doesn't define a resource dictionary implementation, that is left to specific UI frameworks. Pour en savoir plus sur la façon dont les dictionnaires de ressources XAML sont implémentés dans WPF, consultez ressources XAML.To learn more about how XAML resource dictionaries are implemented in WPF, see XAML Resources.

Dans XAML 2006 et WPF, x:Key doit être fourni en tant qu’attribut.In XAML 2006 and WPF, x:Key must be provided as an attribute. Vous pouvez toujours utiliser des clés autres que des chaînes, mais cela requiert qu'une utilisation d'extension de balisage fournisse la valeur autre qu'une chaîne sous la forme d'un attribut.You can still use nonstring keys, but this requires a markup extension usage in order to provide the nonstring value in attribute form. Si vous utilisez XAML 2009, x:Key pouvez être spécifié en tant qu’é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.If you are using XAML 2009, x:Key can be specified as an element, to explicitly support dictionaries keyed by object types other than strings without requiring a markup extension intermediate. Consultez la section « XAML 2009 » dans cette rubrique.See the "XAML 2009" section in this topic. Le reste de la section Remarques s’applique spécifiquement à l’implémentation XAML 2006.The remainder of the Remarks section applies specifically to the XAML 2006 implementation.

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.The attribute value of x:Key can be any string defined in the XamlName Grammar or can be an object evaluated through a markup extension. Consultez les « Remarques sur l'utilisation de WPF » pour obtenir un exemple de WPF.See "WPF Usage Notes" for an example from WPF.

Les éléments enfants d'un élément parent correspondant à une implémentation IDictionary doivent généralement inclure un attribut x:Key qui spécifie une valeur de clé unique dans ce dictionnaire.Child elements of a parent element that is an IDictionary implementation must typically include an x:Key attribute that specifies a unique key value within that dictionary. Les Frameworks peuvent implémenter des propriétés de clé ajoutées en alias pour remplacer x:Key sur les types particuliers ; les types qui définissent de telles propriétés doivent être attribués avec DictionaryKeyPropertyAttribute.Frameworks might implement aliased key properties to substitute for x:Key on particular types; types that define such properties should be attributed with DictionaryKeyPropertyAttribute.

Le code équivalent à la spécification de x:Key est la clé utilisée pour le IDictionary sous-jacent.The code equivalent of specifying x:Key is the key that is used for the underlying IDictionary. Par exemple, un x:Key appliqué au balisage pour 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.For example, an x:Key that is applied in markup for a resource in WPF is equivalent to the value of the key parameter of ResourceDictionary.Add when you add the resource to a WPF ResourceDictionary in code.

Remarques sur l’utilisation de WPFWPF Usage Notes

Les objets enfants d'un objet parent qui est une implémentation IDictionary telle que le ResourceDictionary WPF doivent généralement inclure un attribut x:Key, et la valeur de clé doit être unique dans ce dictionnaire.Child objects of a parent object that is an IDictionary implementation, such as the WPF ResourceDictionary, must typically include an x:Key attribute, and the key value must be unique within that dictionary. Il existe deux exceptions notables :There are two notable exceptions:

Dans le modèle d'application et l'implémentation XAML WPF globale, l'unicité de la clé n'est pas vérifiée par le compilateur de balisage XAML.In the overall WPF XAML implementation and application model, key uniqueness is not checked by the XAML markup compiler. Au lieu de cela, les valeurs manquantes ou non uniques de x:Key provoquent des erreurs de chargement de l'analyseur XAML.Instead, missing or nonunique x:Key values cause load-time XAML parser errors. Toutefois, la gestion de Visual Studio des dictionnaires pour WPF peut souvent noter de telles erreurs dans la phase de conception.However, Visual Studio handling of dictionaries for WPF can often note such errors in the design phase.

Dans la syntaxe affichée, l'objet ResourceDictionary est implicite dans la façon dont le processeur WPF XAML produit une collection pour remplir une collection Resources.Note that in the syntax shown, the ResourceDictionary object is implicit in how the WPF XAML processor produces a collection to populate a Resources collection. ResourceDictionary n'est généralement pas fourni de manière explicite en tant qu'élément dans le balisage, bien qu'il puisse l'être à des fins de clarté (il s'agirait alors d'un élément objet de collection entre l'élément de propriété Resources et les éléments qu'il contient qui remplissent le dictionnaire).A ResourceDictionary is not typically provided explicitly as an element in markup, although it can be in some cases if wanted for clarity (it would be a collection object element between the Resources property element and the items within that populate the dictionary). 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.For information about why a collection object is almost always an implicit element in markup, see XAML Syntax In Detail.

Dans l'implémentation XAML WPF, la gestion pour les clés de dictionnaire de ressources est définie par la classe abstraite ResourceKey.In the WPF XAML implementation, the handling for resource dictionary keys is defined by the ResourceKey abstract class. Toutefois, le processeur WPF XAML produit différents types d'extension sous-jacents pour les clés en fonction de leur utilisation.However the WPF XAML processor produces different underlying extension types for keys based on their usages. Par exemple, la clé d'un DataTemplate ou de classes dérivées est gérée séparément et produit un objet DataTemplateKey distinct.For example, the key for a DataTemplate or any derived class is handled separately, and produces a distinct DataTemplateKey object.

Les clés et les noms utilisent des directives et des éléments de langage différents (x:Key contre x:Name) dans la définition XAML de base.Keys and names use different directives and language elements (x:Key versus x:Name) in the basic XAML definition. Les clés et les noms sont également utilisés dans des situations différentes par la définition WPF et l'application de ces concepts.Keys and names are also used in different situations by the WPF definition and application of these concepts. Pour plus d’informations, consultez portées de code XAML WPF.For details, see WPF XAML Namescopes.

Comme indiqué précédemment, la valeur d'une clé peut être fournie via une extension de balisage et peut être différente d'une valeur de chaîne.As stated previously, the value of a key can be supplied through a markup extension and can be other than a string value. Un exemple de scénario WPF est que la valeur de x:Key peut être un ComponentResourceKey.An example WPF scenario is that the value of x:Key may be a 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 le style totalement.Certain controls expose a style key of that type for a custom style resource that influences part of the appearance and behavior of that control without totally replacing the style. ButtonStyleKey constitue un exemple d'une clé de ce type.An example of such a key is ButtonStyleKey.

La fonctionnalité de dictionnaire fusionné WPF ajoute des considérations supplémentaires concernant l'unicité clé et le comportement de recherche clé.The WPF merged dictionary feature introduces additional considerations for key uniqueness and key lookup behavior. Pour plus d’informations, consultez Dictionnaires de ressources fusionnés.For more information, see Merged Resource Dictionaries.

XAML 2009XAML 2009

XAML 2009 assouplit la restriction qui x:Key toujours être fournie sous forme d’attribut.XAML 2009 relaxes the restriction that x:Key always be provided in attribute form.

Dans WPF, vous pouvez utiliser les fonctionnalités XAML 2009, mais uniquement pour le code XAML qui n’est pas compilé par balisage.In WPF, you can use XAML 2009 features, but only for XAML that is not markup-compiled. 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.Markup-compiled XAML for WPF and the BAML form of XAML do not currently support the XAML 2009 keywords and features.

Sous XAML 2009, vous pouvez spécifier des éléments de x:Key par le biais de l’utilisation suivante :Under XAML 2009, you can specify x:Key elements through the following usage:

Utilisation de l'élément XAML (XAML 2009 uniquement)XAML Element Usage (XAML 2009 only)

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

Valeurs XAMLXAML Values

keyObject Élément objet de l'objet utilisé comme clé pour un object donné dans un dictionnaire spécialisé.Object element for the object that is used as the key for a given object in a specialized dictionary.
  • Le conteneur/parent de ce type d'utilisation n'est pas affiché ici.The container/parent for this kind of use is not shown here. object est censé être un enfant d'un type d'élément objet qui représente une implémentation de dictionnaire spécialisé.object is expected to be a child of an object element that represents a specialized dictionary implementation. keyObject est supposé être une instance de l'objet (ou une valeur d'un type valeur) qui est appropriée comme clé pour cette implémentation de dictionnaire spécialisée particulière.keyObject is expected to be an object instance (or a value of a value type) that is appropriate as the key for that particular specialized dictionary implementation.

  • WPF n'implémente pas les dictionnaires qui requièrent cette utilisation.WPF does not implement dictionaries that require this usage. Les clés d'objet correspondent davantage à une fonctionnalité générale du langage XAML, qui peut s'avérer utile pour certains scénarios de dictionnaire personnalisé où la création du dictionnaire en langage XAML est souhaitable.Object keys is more a general feature of the XAML language, possibly useful for certain custom dictionary scenarios where creating the dictionary in XAML is desirable. 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 pour l'établissement ou la spécification des clés existent, l'utilisation d'une clé d'objet ainsi n'est pas nécessaire.For WPF features such as implicit styles that use non-string keys for resources, other techniques for establishing or specifying the keys exist, so using an object key is not necessary.

  • 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.keyObject could also be a markup extension usage in object element form, rather than a direct object instance.

Notes d'utilisation de SilverlightSilverlight Usage Notes

x:Key pour Silverlight est documenté séparément.x:Key for Silverlight is documented separately. Pour plus d’informations, consultez espace de noms XAML (x :) Fonctionnalités de langage (Silverlight).For more information, see XAML Namespace (x:) Language Features (Silverlight).

Voir aussiSee also