Поделиться через

Директива x:Key

  • Статья

Уникально идентифицирует элементы, которые создаются и ссылаются в определяемом XAML словаре. Добавление значения x:Key в элемент объекта XAML является наиболее распространенным способом идентификации ресурса в словаре ресурсов, например в ResourceDictionaryWPF.

Использование атрибута XAML

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

Использование атрибутов XAML (для WPF)

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

Значения XAML

Ценность Описание
stringKeyValue Текстовая строка, используемая в качестве ключа. Текстовая строка должна соответствовать грамматике XamlName.
markupExtensionUsage В разделителях расширения разметки {}— расширение разметки, которое предоставляет объект для использования в качестве ключа. См. примечания.

Замечания

x:Key поддерживает концепцию словаря ресурсов XAML. XAML как язык не определяет реализацию словаря ресурсов, которая остается в определенных платформах пользовательского интерфейса. Дополнительные сведения о реализации словарей ресурсов XAML в WPF см. в обзоре ресурсов XAML (WPF .NET).

В XAML 2006 и WPF x:Key необходимо предоставить в качестве атрибута. Вы по-прежнему можете использовать нестроки, но это требует использования расширения разметки для предоставления значения нестроки в форме атрибута. Если вы используете XAML 2009, x:Key можно указать как элемент, чтобы явно поддерживать словари, ключи которых используются типами объектов, отличными от строк, без необходимости промежуточного расширения разметки. См. раздел "XAML 2009" в этом разделе. Оставшаяся часть раздела "Примечания" применяется специально к реализации XAML 2006.

Значение атрибута x:Key может быть любой строкой, определенной в грамматики XamlName, или объектом, вычисляемым с помощью расширения разметки. Пример из WPF см. в разделе "Заметки об использовании WPF".

Дочерние элементы родительского элемента, который является реализацией IDictionary, обычно должны включать атрибут x:Key, указывающий уникальное значение ключа в этом словаре. Платформы могут реализовать псевдонимированные ключевые свойства для замены x:Key на определенные типы; типы, определяющие такие свойства, должны быть атрибутами DictionaryKeyPropertyAttribute.

Эквивалент кода, указывающий x:Key, является ключом, используемым для базовой IDictionary. Например, x:Key, применяемый в разметке для ресурса в WPF, эквивалентен значению параметра keyResourceDictionary.Add при добавлении ресурса в ResourceDictionary WPF в коде.

Заметки об использовании WPF

Дочерние объекты родительского объекта, являющегося реализацией IDictionary, например ResourceDictionaryWPF, обычно должны включать атрибут x:Key, а значение ключа должно быть уникальным в этом словаре. Существует два важных исключения:

  • Некоторые типы WPF объявляют неявный ключ для использования словаря. Например, Style с TargetTypeили DataTemplate с DataType, могут находиться в ResourceDictionary и использовать неявный ключ.

  • WPF поддерживает объединенную концепцию словаря ресурсов. Ключи можно совместно использовать между объединенными словарями, а к общему поведению ключей можно получить доступ с помощью FindResource. Дополнительные сведения см. в словаря объединенных ресурсов.

В общей реализации и модели приложения WPF ключ уникальности ключа не проверяется компилятором разметки XAML. Вместо этого отсутствующие или неуниковые значения x:Key вызывают ошибки средства синтаксического анализа XAML во время загрузки. Однако обработка словарей WPF Visual Studio часто может заметить такие ошибки на этапе разработки.

Обратите внимание, что в приведенном синтаксисе объект ResourceDictionary неявен в том, как обработчик XAML WPF создает коллекцию для заполнения коллекции Resources. ResourceDictionary обычно не предоставляется явным образом как элемент в разметке, хотя он может быть в некоторых случаях, если он требуется для ясности (это будет элемент объекта коллекции между элементом свойства Resources и элементами в этом заполнении словаря). Сведения о том, почему объект коллекции почти всегда является неявным элементом в разметке, см. в синтаксисе XAML в подробной.

В реализации XAML WPF обработка ключей словаря ресурсов определяется ResourceKey абстрактным классом. Однако обработчик XAML WPF создает различные базовые типы расширений для ключей на основе их использования. Например, ключ для DataTemplate или любого производного класса обрабатывается отдельно и создает отдельный объект DataTemplateKey.

Ключи и имена используют различные директивы и элементы языка (x:Key и x:Name) в базовом определении XAML. Ключи и имена также используются в различных ситуациях определением WPF и применением этих понятий. Дополнительные сведения см. в области имен XAML WPF.

Как упоминалось ранее, значение ключа может быть предоставлено через расширение разметки и может отличаться от строкового значения. Пример сценария WPF заключается в том, что значение x:Key может быть ComponentResourceKey. Некоторые элементы управления предоставляют ключ стиля этого типа для ресурса пользовательского стиля, который влияет на внешний вид и поведение этого элемента управления без полной замены стиля. Примером такого ключа является ButtonStyleKey.

Функция объединенного словаря WPF содержит дополнительные рекомендации по уникальности ключей и поведению подстановки ключей. Дополнительные сведения см. в словаря объединенных ресурсов.

XAML 2009

XAML 2009 смягчает ограничение, которое x:Key всегда предоставляться в форме атрибута.

В WPF можно использовать функции XAML 2009, но только для XAML, который не компилируется разметкой. Скомпилированный разметкой XAML для WPF и форма BAML XAML в настоящее время не поддерживают ключевые слова и функции XAML 2009.

В XAML 2009 можно указать элементы x:Key с помощью следующего использования:

Использование элементов XAML (только XAML 2009)

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

Значения XAML

Ценность Описание
keyObject Элемент Object для объекта, который используется в качестве ключа для заданного object в специализированном словаре.

  • Контейнер или родительский объект для этого типа использования не отображается здесь. ожидается, что object будет дочерним элементом объекта, который представляет специализированную реализацию словаря. keyObject, как ожидается, будет экземпляром объекта (или значением типа значения), соответствующим ключом для конкретной специализированной реализации словаря.

  • WPF не реализует словари, требующие этого использования. Ключи объектов являются более общей особенностью языка XAML, возможно, полезной для определенных сценариев пользовательского словаря, в которых создание словаря в XAML является желательным. Для таких функций WPF, как неявные стили, использующие нестроковые ключи для ресурсов, другие методы установки или указания ключей существуют, поэтому использование ключа объекта не требуется.

  • keyObject также может быть расширением разметки в форме элемента объекта, а не прямым экземпляром объекта.

Заметки об использовании Silverlight

x:Key для Silverlight документируется отдельно. Дополнительные сведения см. впространства имен XAML (x:).

См. также