x:Key-Direktive
Kennzeichnet Elemente eindeutig, die in einem XAML-definierten Wörterbuch erstellt und referenziert werden.
Verwendung von XAML-Attributen
<object x:Key="stringKeyValue".../>
-or-
<object x:Key="{markupExtensionUsage}".../>
Verwendung von XAML-Attributen (WPF-spezifisch)
<object.Resources>
<object x:Key="stringKeyValue".../>
</object.Resources>
-or-
<object.Resources>
<object x:Key="{markupExtensionUsage}".../>
</object.Resources>
XAML-Werte
stringKeyValue |
Eine Textzeichenfolge, die als Schlüssel verwendet werden soll. Die Textzeichenfolge muss XamlName-Grammatik entsprechen. |
markupExtensionUsage |
Innerhalb der Markuperweiterungstrennzeichen {}, eine Markuperweiterungsverwendung, die ein Objekt bereitstellt, das als Schlüssel verwendet werden soll. Siehe Hinweise. |
Hinweise
In XAML 2006 und WPF muss x:Key als Attribut bereitgestellt werden. Sie können immer noch Nicht-Zeichenfolge-Schlüssel verwenden, aber dies erfordert eine Markuperweiterungsverwendung, um den Nicht-Zeichenfolgenwert in Attributform bereitzustellen. Wenn XAML 2009 verwendet wird, kann x:Key als ein Element angegeben werden, das Wörterbücher explizit unterstützt, die von Objekttypen, die keine Zeichenfolgen sind, verschlüsselt wurden, ohne eine Markuperweiterung (Intermediate) zu erfordern. Weitere Informationen finden Sie im Abschnitt "XAML 2009" in diesem Thema. Der Rest des Hinweisabschnitts bezieht sich ausdrücklich auf die XAML 2006-Implementierung.
Der Attributwert von x:Key kann jede in XamlName-Grammatik definierte Zeichenfolge oder ein durch eine Markuperweiterung ausgewertetes Objekt sein. Ein Beispiel aus WPF finden Sie unter "Hinweise zur WPF-Verwendung".
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. 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.
Das Codeäquivalent zum Festlegen von x:Key ist der Schlüssel, wie er für den zugrunde liegenden IDictionary verwendet wird. So entspricht z. B. ein im Markup angewendeter x:Key dem Wert des key-Parameters von ResourceDictionary.Add, wenn Sie die Ressource einem WPF ResourceDictionary im Code hinzufügen.
Hinweise zur WPF-Verwendung
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. Dabei gelten zwei wichtige Ausnahmen:
Einige WPF-Typen deklarieren einen impliziten Schlüssel für Wörterbuchverwendung. 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.
WPF unterstützt das Konzept zusammengeführter Ressourcenwörterbücher. 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. Weitere Informationen finden Sie unter Zusammengeführte Ressourcenwörterbücher.
In der gesamten WPF-XAML-Implementierung und im Anwendungsmodell wird die Eindeutigkeit der Schlüssel nicht vom XAML-Markupcompiler überprüft. Stattdessen führen fehlende oder nicht eindeutige x:Key-Werte zu XAML-Parser-Ladezeitfehlern. Allerdings kann die Visual Studio-Behandlung von Wörterbüchern für WPF solche Fehler in der Entwurfsphase häufig beachten.
Beachten Sie, dass in der angegebenen Syntax bei der Erzeugung einer Auflistung durch den WPF-XAML-Prozessor, um eine Resources-Auflistung aufzufüllen, das ResourceDictionary-Objekt implizit ist. 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). Informationen dazu, warum ein Auflistungsobjekt fast immer ein implizites Element im Markup ist, finden Sie unter Ausführliche Erläuterung der XAML-Syntax.
In der WPF XAML-Implementierung wird die Handhabung Ressourcenwörterbuchschlüssel durch die abstrakte ResourceKey-Klasse definiert. Der WPF-XAML-Prozessor erstellt jedoch je nach ihrer Verwendung unterschiedliche zugrunde liegende Erweiterungstypen für Schlüssel. So wird z. B. der Schlüssel für DataTemplate oder abgeleitete Klassen getrennt verarbeitet und ein anderes DataTemplateKey-Objekt erstellt.
Schlüssel und Namen verwenden andere Direktiven und Sprachelemente (x:Key gegenüber x:Name) in der grundlegenden XAML-Definition. Schlüssel und Namen werden auch in unterschiedlichen Situationen von der WPF-Definition und Anwendung dieser Konzepte genutzt. Ausführliche Informationen finden Sie unter WPF-XAML-Namescopes.
Wie zuvor angegeben, kann der Wert eines Schlüssels durch eine Markuperweiterung angegeben werden und braucht kein Zeichenfolgenwert zu sein. Ein Beispiel-WPF-Szenario ist, dass der Wert von x:Key ein ComponentResourceKey sein kann. 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. Ein Beispiel für einen solchen Schlüssel ist ButtonStyleKey.
Die zusammengeführte Wörterbuchfunktion von WPF führt weitere Überlegungen für Schlüsseleindeutigkeit und Schlüsselsuchverhalten ein. Weitere Informationen finden Sie unter Zusammengeführte Ressourcenwörterbücher.
XAML 2009
XAML 2009 lockert die Einschränkung, dass x:Key immer in Attributform bereitgestellt wird.
In WPF können Sie XAML 2009-Funktionen verwenden, jedoch nur für XAML, die nicht markupkompiliert ist. Markupkompilierte XAML für WPF und die BAML-Form von XAML unterstützen die XAML 2009-Schlüsselwörter und -Funktionen derzeit nicht.
In XAML 2009 können Sie x:Key-Elemente durch die folgende Syntax angeben:
XAML-Elementverwendung (nur XAML 2009)
<object>
<x:Key>
keyObject
</x:Key>
...
</object>
XAML-Werte
keyObject |
Objektelement für das Objekt, das für ein angegebenes object in einem spezialisierten Wörterbuch als Schlüssel verwendet wird. |
Der Container/das übergeordnete Element für diesen Typ der Verwendung wird nicht hier angezeigt. object wird erwartungsgemäß ein untergeordnetes Element einer Art von Objektelement sein, das eine spezialisierte Wörterbuchimplementierung darstellt. keyObject wird erwartet, eine Objektinstanz (oder ein Wert eines Werttyps) zu sein, die als Schlüssel für diese spezialisierte Wörterbuchimplementierung geeignet ist.
WPF implementiert keine Wörterbücher, die diese Verwendung erfordern. Objektschlüssel sind eine allgemeinere Funktion der XAML-Sprache, möglicherweise nützlich für bestimmte Benutzerwörterbuchszenarien, in denen das Erstellen des Wörterbuchs in XAML wünschenswert ist. Bei WPF-Funktionen, z. B. implizite Formate, die nicht-Zeichenfolge-Schlüssel für Ressourcen verwenden, sind andere Techniken für das Festlegen oder das Angeben der Schlüssel vorhanden, deshalb ist es nicht notwendig, einen Objektschlüssel zu verwenden.
keyObject könnte auch eine Markuperweiterungsverwendung in Objektelementform sein, statt einer direkten Objektinstanz.
Silverlight-Verwendungshinweise
x:Key für Silverlight wird separat dokumentiert. Weitere Informationen finden Sie unter Sprachfeatures des XAML-Namespace (x:).
Siehe auch
Referenz
StaticResource-Markuperweiterung