x:Key-Anweisungx:Key Directive

Kennzeichnet Elemente eindeutig, die in einem XAML-definierten Wörterbuch erstellt und referenziert werden.Uniquely identifies elements that are created and referenced in a XAML-defined dictionary. Einem XAML-Objektelement einen x:Key-Wert hinzuzufügen, ist der üblichste Weg, um eine Ressource in einem Ressourcenwörterbuch, beispielsweise in einem WPF- ResourceDictionary zu identifizieren.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.

Verwendung von XAML-AttributenXAML Attribute Usage

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

Verwendung von XAML-Attributen (WPF-spezifisch)XAML Attribute Usage (WPF-specific)

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

XAML-WerteXAML Values

stringKeyValue Eine Textzeichenfolge, die als Schlüssel verwendet werden soll.A text string to use as a key. Die Zeichenfolge muss entsprechen den XamlName-Grammatik.The text string must conform to the XamlName Grammar.
markupExtensionUsage In den Markup Extension Trennzeichen {}, eine Markuperweiterungsverwendung, die ein Objekt, das als Schlüssel bereitstellt.Within the markup extension delimiters {}, a markup extension usage that provides an object to use as a key. Siehe Hinweise.See Remarks.

HinweiseRemarks

x:Key unterstützt das XAML-Ressourcenwörterbuchkonzept.x:Key supports the XAML resource dictionary concept. XAML als Sprache definiert keine Ressourcenwörterbuchimplementierung, die spezifischen Benutzeroberflächen-Frameworks vorbehalten bleibt.XAML as a language doesn't define a resource dictionary implementation, that is left to specific UI frameworks. Um weitere Informationen dazu, wie XAML-Ressourcenwörterbücher in WPF implementiert werden, finden Sie unter XAML-Ressourcen.To learn more about how XAML resource dictionaries are implemented in WPF, see XAML Resources.

In XAML 2006 und WPF x:Key muss als Attribut angegeben werden.In XAML 2006 and WPF, x:Key must be provided as an attribute. Sie können immer noch Nichtzeichenfolgeschlüssel verwenden, aber dies erfordert eine Markuperweiterungsverwendung, um den Nichtzeichenfolgenwert in Attributform bereitzustellen.You can still use nonstring keys, but this requires a markup extension usage in order to provide the nonstring value in attribute form. Bei Verwendung von XAML 2009 x:Key kann angegeben werden als ein Element ohne einen Markuperweiterungs-Zeichenfolgen nach Objekttypen sortiert, außer Wörterbücher explizit unterstützt.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. Finden Sie im Abschnitt "XAML 2009" in diesem Thema.See the "XAML 2009" section in this topic. Der Rest der Abschnitt "Hinweise" bezieht sich speziell auf die XAML 2006-Implementierung.The remainder of the Remarks section applies specifically to the XAML 2006 implementation.

Den Wert des Attributs x:Key kann eine beliebige Zeichenfolge in definiert werden die XamlName-Grammatik oder eine durch eine Markuperweiterung ausgewertetes Objekt sein.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. Ein Beispiel aus WPF finden Sie unter "Hinweise zur WPF-Verwendung".See "WPF Usage Notes" for an example from WPF.

Untergeordnete Elemente eines übergeordneten Elements, bei dem es sich um eine IDictionary-Implementierung handelt, müssen im Allgemeinen ein x:Key-Attribut enthalten, das einen eindeutigen Schlüsselwert in diesem Wörterbuch angibt.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. Frameworks könnten als Alias definierte Schlüsseleigenschaften implementieren, um x:Key bei bestimmten Typen zu vertreten; Typen, die solche Eigenschaften definieren, sollten mit dem Attribut DictionaryKeyPropertyAttribute versehen werden.Frameworks might implement aliased key properties to substitute for x:Key on particular types; types that define such properties should be attributed with DictionaryKeyPropertyAttribute.

Das Codeäquivalent zum Festlegen von x:Key ist der Schlüssel, wie er für den zugrunde liegenden IDictionary verwendet wird.The code equivalent of specifying x:Key is the key that is used for the underlying IDictionary. So entspricht z. B. ein im Markup für eine Ressource in WPF angewendeter x:Key dem Wert des key-Parameters von ResourceDictionary.Add, wenn Sie die Ressource einem WPF ResourceDictionary im Code hinzufügen.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.

Hinweise zur WPF-VerwendungWPF Usage Notes

Untergeordnete Objekte eines übergeordneten Objekts, bei dem es sich um eine IDictionary-Implementierung wie z. B. WPF ResourceDictionary handelt, müssen im Allgemeinen ein x:Key-Attribut enthalten, und der Schlüsselwert muss in diesem Wörterbuch eindeutig sein.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. Dabei gelten zwei wichtige Ausnahmen:There are two notable exceptions:

  • Einige WPF-Typen deklarieren einen impliziten Schlüssel für Wörterbuchverwendung.Some WPF types declare an implicit key for dictionary usage. Zum Beispiel kann sich ein Style mit einem TargetType oder ein DataTemplate mit einem DataType in einem ResourceDictionary befinden und den impliziten Schlüssel verwenden.For example, a Style with a TargetType, or a DataTemplate with a DataType, can be in a ResourceDictionary and use the implicit key.

  • WPF unterstützt das Konzept zusammengeführter Ressourcenwörterbücher.WPF supports a merged resource dictionary concept. Schlüssel können zwischen den zusammengeführten Wörterbüchern freigegeben sein, und auf das Verhalten der freigegebenen Schlüssel kann mit FindResource zugegriffen werden.Keys can be shared between the merged dictionaries, and the shared key behavior can be accessed using FindResource. Weitere Informationen finden Sie unter Zusammengeführte Ressourcenverzeichnisse.For more information, see Merged Resource Dictionaries.

In der gesamten WPF-XAML-Implementierung und im Anwendungsmodell wird die Eindeutigkeit der Schlüssel nicht vom XAML-Markupcompiler überprüft.In the overall WPF XAML implementation and application model, key uniqueness is not checked by the XAML markup compiler. Stattdessen führen fehlende oder nicht eindeutige x:Key-Werte zu XAML-Parser-Ladezeitfehlern.Instead, missing or nonunique x:Key values cause load-time XAML parser errors. Allerdings kann Visual Studio-Behandlung von Wörterbüchern für WPF solche Fehler häufig in der Entwurfsphase beachten.However, Visual Studio handling of dictionaries for WPF can often note such errors in the design phase.

Beachten Sie, dass in der angegebenen Syntax bei der Erzeugung einer Auflistung durch den WPF-XAML-Prozessor, um eine ResourceDictionary-Auflistung aufzufüllen, das Resources-Objekt implizit ist.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. Ein ResourceDictionary wird in der Regel nicht explizit als Element im Markup bereitgestellt, obwohl dies in einigen Fällen aus Gründen der Anschaulichkeit möglich ist (hierbei würde es sich um ein Eigenschaftenelement der Auflistung zwischen dem Resources-Eigenschaftenelement und den darin enthaltenen Elementen handeln, von denen das Wörterbuch gefüllt wird).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). Informationen dazu, warum ein Auflistungsobjekt fast immer ein implizites Element im Markup ist, finden Sie unter XAML-Syntax im Detail.For information about why a collection object is almost always an implicit element in markup, see XAML Syntax In Detail.

In der WPF XAML-Implementierung wird die Handhabung von Ressourcenwörterbuchschlüsseln durch die abstrakte ResourceKey-Klasse definiert.In the WPF XAML implementation, the handling for resource dictionary keys is defined by the ResourceKey abstract class. Der WPF-XAML-Prozessor erstellt jedoch je nach ihrer Verwendung unterschiedliche zugrunde liegende Erweiterungstypen für Schlüssel.However the WPF XAML processor produces different underlying extension types for keys based on their usages. So wird z. B. der Schlüssel für DataTemplate oder abgeleitete Klassen getrennt verarbeitet, und er erstellt ein anderes DataTemplateKey-Objekt.For example, the key for a DataTemplate or any derived class is handled separately, and produces a distinct DataTemplateKey object.

Schlüssel und Namen verwenden unterschiedliche Direktiven und Sprachelemente (x:Key gegenüber x:Name) in der grundlegenden XAML-Definition.Keys and names use different directives and language elements (x:Key versus x:Name) in the basic XAML definition. Schlüssel und Namen werden auch in unterschiedlichen Situationen von der WPF-Definition und Anwendung dieser Konzepte genutzt.Keys and names are also used in different situations by the WPF definition and application of these concepts. Weitere Informationen finden Sie unter WPF-XAML-Namescopes.For details, see WPF XAML Namescopes.

Wie zuvor angegeben, kann der Wert eines Schlüssels durch eine Markuperweiterung angegeben werden und braucht kein Zeichenfolgenwert zu sein.As stated previously, the value of a key can be supplied through a markup extension and can be other than a string value. Ein Beispielszenario für die WPF-ist der Wert des x:Key möglicherweise eine ComponentResourceKey.An example WPF scenario is that the value of x:Key may be a ComponentResourceKey. Bestimmte Steuerelemente machen einen Stilschlüssel dieses Typs verfügbar, mit dem eine benutzerdefinierte Stilressource erstellt werden kann, die einen Teil des Aussehens und Verhaltens dieses Steuerelements beeinflusst, ohne den Stil vollständig zu ersetzen.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. Ein Beispiel für einen solchen Schlüssel ist ButtonStyleKey.An example of such a key is ButtonStyleKey.

Die zusammengeführte Wörterbuchfunktion von WPF führt weitere Überlegungen zur Schlüsseleindeutigkeit und zum Schlüsselsuchverhalten ein.The WPF merged dictionary feature introduces additional considerations for key uniqueness and key lookup behavior. Weitere Informationen finden Sie unter Zusammengeführte Ressourcenverzeichnisse.For more information, see Merged Resource Dictionaries.

XAML 2009XAML 2009

XAML 2009 lockert die Einschränkung, die x:Key immer in Attributform bereitgestellt werden.XAML 2009 relaxes the restriction that x:Key always be provided in attribute form.

In WPF können Sie XAML 2009-Funktionen, jedoch nur für XAML, die nicht markupkompiliert ist.In WPF, you can use XAML 2009 features, but only for XAML that is not markup-compiled. Markupkompilierte XAML für WPF und die BAML-Form von XAML unterstützen die XAML 2009-Schlüsselwörter und -Funktionen derzeit nicht.Markup-compiled XAML for WPF and the BAML form of XAML do not currently support the XAML 2009 keywords and features.

Sie können in XAML 2009 angeben x:Key Elemente durch die folgende Syntax:Under XAML 2009, you can specify x:Key elements through the following usage:

XAML-Elementverwendung (nur XAML 2009)XAML Element Usage (XAML 2009 only)

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

XAML-WerteXAML Values

keyObject Objektelement für das Objekt, das für ein angegebenes object in einem spezialisierten Wörterbuch als Schlüssel verwendet wird.Object element for the object that is used as the key for a given object in a specialized dictionary.
  • Der Container/das übergeordnete Element für diesen Typ der Verwendung wird hier nicht angezeigt.The container/parent for this kind of use is not shown here. object wird erwartungsgemäß ein untergeordnetes Element eines Objektelements sein, das eine spezialisierte Wörterbuchimplementierung darstellt.object is expected to be a child of an object element that represents a specialized dictionary implementation. keyObject ist erwartungsgemäß eine Objektinstanz (oder ein Wert eines Werttyps), die als Schlüssel für diese bestimmte spezialisierte Wörterbuchimplementierung geeignet ist.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 implementiert keine Wörterbücher, die diese Verwendung erfordern.WPF does not implement dictionaries that require this usage. Objektschlüssel sind eine allgemeinere Funktion der XAML-Sprache. Sie sind möglicherweise nützlich für bestimmte Benutzerwörterbuchszenarien, in denen das Erstellen des Wörterbuchs in XAML wünschenswert ist.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. Bei WPF-Funktionen, wie beispielsweise impliziten Stilen, die für Ressourcen Schlüssel verwenden, die keine Zeichenfolgen sind, gibt es andere Techniken für das Festlegen oder das Angeben der Schlüssel. Deshalb ist es nicht notwendig, einen Objektschlüssel zu verwenden.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 möglicherweise auch eine Markuperweiterungsverwendung in Objektelementform anstelle einer direkten Objektinstanz.keyObject could also be a markup extension usage in object element form, rather than a direct object instance.

Silverlight-VerwendungshinweiseSilverlight Usage Notes

x:Key für Silverlight wird separat dokumentiert.x:Key for Silverlight is documented separately. Weitere Informationen finden Sie unter XAML-Namespace (x:)) Sprachfunktionen (Silverlight).For more information, see XAML Namespace (x:) Language Features (Silverlight).

Siehe auchSee also