Udostępnij za pośrednictwem

x:Key, dyrektywa

  • Artykuł

Unikatowo identyfikuje elementy, które są tworzone i przywoływały się w słowniku zdefiniowanym przez język XAML. Dodawanie wartości x:Key do elementu obiektu XAML jest najczęstszym sposobem identyfikowania zasobu w słowniku zasobów, na przykład w ResourceDictionaryWPF.

Użycie atrybutu XAML

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

Użycie atrybutów XAML (specyficzne dla platformy WPF)

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

Wartości XAML

Wartość Opis
stringKeyValue Ciąg tekstowy do użycia jako klucz. Ciąg tekstowy musi być zgodny z XamlName Grammar.
markupExtensionUsage W ogranicznikach rozszerzeń znaczników {}użycie rozszerzenia znaczników, które udostępnia obiekt do użycia jako klucz. Zobacz uwagi.

Uwagi

x:Key obsługuje koncepcję słownika zasobów XAML. Język XAML jako język nie definiuje implementacji słownika zasobów, która jest pozostawiona określonym strukturom interfejsu użytkownika. Aby dowiedzieć się więcej na temat sposobu implementacji słowników zasobów XAML w WPF, zobacz Overview of XAML resources (WPF .NET) (Omówienie zasobów XAML (WPF .NET).

W XAML 2006 i WPF x:Key należy podać jako atrybut. Nadal można używać kluczy nieciągujących, ale wymaga to użycia rozszerzenia znaczników, aby podać wartość nieciągniętą w postaci atrybutu. Jeśli używasz języka XAML 2009, x:Key można określić jako element, aby jawnie obsługiwać słowniki kluczowane przez typy obiektów innych niż ciągi bez wymagania pośredniego rozszerzenia znaczników. Zobacz sekcję "XAML 2009" w tym temacie. Pozostała część sekcji Uwagi dotyczy konkretnie implementacji XAML 2006.

Wartość atrybutu x:Key może być dowolnym ciągiem zdefiniowanym w XamlName Grammar lub może być obiektem ocenianym za pomocą rozszerzenia znaczników. Zobacz "Uwagi dotyczące użycia WPF", aby zapoznać się z przykładem z WPF.

Elementy podrzędne elementu nadrzędnego, który jest implementacją IDictionary, muszą zazwyczaj zawierać atrybut x:Key, który określa unikatową wartość klucza w tym słowniku. Struktury mogą implementować właściwości klucza aliasu, aby zastąpić x:Key w określonych typach; typy definiujące takie właściwości powinny być przypisywane DictionaryKeyPropertyAttribute.

Odpowiednikiem kodu określania x:Key jest klucz używany dla bazowego IDictionary. Na przykład x:Key, która jest stosowana w adiustacji dla zasobu w WPF, jest równoważna wartości parametru keyResourceDictionary.Add podczas dodawania zasobu do ResourceDictionary WPF w kodzie.

Uwagi dotyczące użycia platformy WPF

Obiekty podrzędne obiektu nadrzędnego, który jest implementacją IDictionary, taką jak WPF ResourceDictionary, muszą zazwyczaj zawierać atrybut x:Key, a wartość klucza musi być unikatowa w tym słowniku. Istnieją dwa istotne wyjątki:

  • Niektóre typy WPF deklarują niejawny klucz do użycia słownika. Na przykład Style z TargetTypelub DataTemplate z DataTypemoże znajdować się w ResourceDictionary i używać klucza niejawnego.

  • Platforma WPF obsługuje scaloną koncepcję słownika zasobów. Klucze mogą być współużytkowane między scalonych słowników, a dostęp do klucza współużytkowanego można uzyskać przy użyciu FindResource. Aby uzyskać więcej informacji, zobacz słowniki zasobów scalonych .

W ogólnej implementacji I modelu aplikacji WPF XAML kluczowa unikatowość nie jest sprawdzana przez kompilator znaczników XAML. Zamiast tego brakujące lub niepowiązane wartości x:Key powodują błędy analizatora XAML w czasie ładowania. Jednak obsługa słowników w programie Visual Studio dla WPF często może zauważyć takie błędy w fazie projektowania.

Należy pamiętać, że w pokazanej składni obiekt ResourceDictionary jest niejawny w sposobie tworzenia kolekcji WPF XAML w celu wypełnienia kolekcji Resources. ResourceDictionary nie jest zwykle podawana jawnie jako element w adiustacji, chociaż w niektórych przypadkach może być to element obiektu kolekcji między elementem właściwości Resources a elementami w tym słowniku. Aby uzyskać informacje o tym, dlaczego obiekt kolekcji jest prawie zawsze niejawnym elementem w znacznikach, zobacz Składnia XAML w szczegółach.

W implementacji WPF XAML obsługa kluczy słownika zasobów jest definiowana przez klasę abstrakcyjną ResourceKey. Jednak procesor XAML WPF tworzy różne podstawowe typy rozszerzeń dla kluczy na podstawie ich użycia. Na przykład klucz dla DataTemplate lub dowolnej klasy pochodnej jest obsługiwany oddzielnie i tworzy odrębny obiekt DataTemplateKey.

Klucze i nazwy używają różnych dyrektyw i elementów języka (x:Key a x:Name) w podstawowej definicji XAML. Klucze i nazwy są również używane w różnych sytuacjach przez definicję WPF i zastosowanie tych pojęć. Aby uzyskać szczegółowe informacje, zobacz WPF XAML Namescopes.

Jak wspomniano wcześniej, wartość klucza można podać za pomocą rozszerzenia znaczników i może być inna niż wartość ciągu. Przykładem scenariusza WPF jest to, że wartość x:Key może być ComponentResourceKey. Niektóre kontrolki uwidaczniają klucz stylu tego typu dla zasobu stylu niestandardowego, który wpływa na część wyglądu i zachowania tej kontrolki bez całkowitego zastąpienia stylu. Przykładem takiego klucza jest ButtonStyleKey.

Funkcja słownika scalonego WPF wprowadza dodatkowe zagadnienia dotyczące unikatowości klucza i zachowania wyszukiwania kluczy. Aby uzyskać więcej informacji, zobacz słowniki zasobów scalonych .

XAML 2009

XAML 2009 zrelaksuje ograniczenie, które x:Key zawsze być podane w postaci atrybutu.

W WPF można używać funkcji XAML 2009, ale tylko dla języka XAML, który nie jest skompilowany. Kod XAML skompilowany w języku XAML dla platformy WPF i formularza BAML języka XAML nie obsługuje obecnie słów kluczowych i funkcji XAML 2009.

W obszarze XAML 2009 można określić elementy x:Key za pomocą następującego użycia:

Użycie elementu XAML (tylko XAML 2009)

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

Wartości XAML

Wartość Opis
keyObject Element object dla obiektu, który jest używany jako klucz dla danego object w wyspecjalizowanym słowniku.

  • Kontener/element nadrzędny dla tego rodzaju użycia nie jest pokazany tutaj. object powinien być elementem podrzędnym elementu obiektu, który reprezentuje wyspecjalizowaną implementację słownika. keyObject oczekuje się wystąpienia obiektu (lub wartości typu wartości), które jest odpowiednie jako klucz dla tej konkretnej wyspecjalizowanej implementacji słownika.

  • WPF nie implementuje słowników, które wymagają tego użycia. Klucze obiektów to bardziej ogólna funkcja języka XAML, co może być przydatne w przypadku niektórych scenariuszy słownika niestandardowego, w których tworzenie słownika w języku XAML jest pożądane. W przypadku funkcji WPF, takich jak style niejawne, które używają kluczy innych niż ciąg dla zasobów, inne techniki ustanawiania lub określania kluczy istnieją, więc użycie klucza obiektu nie jest konieczne.

  • keyObject może być również użyciem rozszerzenia znaczników w formularzu elementu obiektu, a nie bezpośrednim wystąpieniem obiektu.

Informacje o użyciu programu Silverlight

x:Key dla programu Silverlight jest udokumentowany oddzielnie. Aby uzyskać więcej informacji, zobacz przestrzeni nazw XAML (x:) Funkcje językowe (Silverlight).

Zobacz też