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

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

  • Статья

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

Использование атрибута 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

Стоимость Description
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, эквивалентна значению параметра key из словаря ResourceDictionary.Add, при добавлении ресурса в WPF ResourceDictionary в коде.

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

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

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

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

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

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

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

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

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

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

XAML 2009

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

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

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

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

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

Значения XAML

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

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

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

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

Примечания об использовании Silverlight

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

См. также