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

Уникально идентифицирует элементы, создаваемые и упоминаемые в словаре, определенном в XAML.Uniquely identifies elements that are created and referenced in a XAML-defined dictionary. Добавление x:Key значения в объектный элемент XAML является наиболее распространенным способом для обнаружения ресурса в словаре ресурсов, например в ResourceDictionaryWPF.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.

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

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

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

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

Значения XAMLXAML Values

stringKeyValue Текстовая строка, используемая в качестве ключа.A text string to use as a key. Текстовая строка должна соответствовать грамматике имяxaml.The text string must conform to the XamlName Grammar.
markupExtensionUsage В пределах разделителей расширений разметки {}использование расширения разметки, которое предоставляет объект для использования в качестве ключа.Within the markup extension delimiters {}, a markup extension usage that provides an object to use as a key. См. заметки.See Remarks.

ЗаметкиRemarks

x:Key поддерживает концепцию словаря ресурсов XAML.x:Key supports the XAML resource dictionary concept. XAML в качестве языка не определяет реализацию словаря ресурсов, которая оставлена определенным платформам пользовательского интерфейса.XAML as a language doesn't define a resource dictionary implementation, that is left to specific UI frameworks. Дополнительные сведения о реализации словарей ресурсов XAML в WPF см. в разделе ресурсы XAML.To learn more about how XAML resource dictionaries are implemented in WPF, see XAML Resources.

В XAML 2006 и WPF x:Key должны быть предоставлены в качестве атрибута.In XAML 2006 and WPF, x:Key must be provided as an attribute. Вы по-прежнему можете использовать Нестроковые ключи, но для этого требуется использование расширения разметки, чтобы предоставить нестроковое значение в форме атрибута.You can still use nonstring keys, but this requires a markup extension usage in order to provide the nonstring value in attribute form. Если вы используете XAML 2009, x:Key можно указать в качестве элемента, чтобы явно поддерживать словари, ключи которых отличаются от типов строк, не требуя промежуточного расширения разметки.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. См. раздел "XAML 2009" этой статьи.See the "XAML 2009" section in this topic. Оставшаяся часть раздела «Примечания» относится только к реализации XAML 2006.The remainder of the Remarks section applies specifically to the XAML 2006 implementation.

Значением атрибута x:Key может быть любая строка, определенная в грамматике имяxaml , или объект, вычисленный с помощью расширения разметки.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. Пример из WPF см. в разделе "Примечания об использовании WPF".See "WPF Usage Notes" for an example from WPF.

Дочерние элементы родительского элемента, который является реализацией IDictionary, обычно должны включать атрибут x:Key, указывающий уникальное значение ключа в этом словаре.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. Платформы могут реализовывать свойства ключа с псевдонимами для замены x:Key в определенных типах; типы, определяющие такие свойства, должны иметь атрибут DictionaryKeyPropertyAttribute.Frameworks might implement aliased key properties to substitute for x:Key on particular types; types that define such properties should be attributed with DictionaryKeyPropertyAttribute.

Код, эквивалентный указанию x:Key, является ключом, используемым для базового IDictionary.The code equivalent of specifying x:Key is the key that is used for the underlying IDictionary. Например, x:Key, применяемая в разметке для ресурса в WPF, эквивалентна значению параметра key в ResourceDictionary.Add при добавлении ресурса в ResourceDictionary WPF в коде.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.

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

Дочерние объекты родительского объекта, который является реализацией IDictionary, например ResourceDictionaryWPF, обычно должны включать атрибут x:Key, а значение ключа должно быть уникальным в пределах этого словаря.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. Существуют два важных исключения.There are two notable exceptions:

  • Некоторые типы WPF объявляют неявный ключ для использования словаря.Some WPF types declare an implicit key for dictionary usage. Например, Style с TargetTypeили DataTemplate с DataType, может быть в ResourceDictionary и использовать неявный ключ.For example, a Style with a TargetType, or a DataTemplate with a DataType, can be in a ResourceDictionary and use the implicit key.

  • WPF поддерживает концепцию объединенного словаря ресурсов.WPF supports a merged resource dictionary concept. Ключи могут совместно использоваться объединенными словарями, а поведение общего ключа можно получить с помощью FindResource.Keys can be shared between the merged dictionaries, and the shared key behavior can be accessed using FindResource. Подробнее см. в разделе Объединенные словари ресурсов.For more information, see Merged Resource Dictionaries.

В общей реализации XAML и модели приложения WPF Уникальность ключа не проверяется компилятором разметки XAML.In the overall WPF XAML implementation and application model, key uniqueness is not checked by the XAML markup compiler. Вместо этого отсутствующие или неуникальные значения x:Key вызывают ошибки синтаксического анализатора XAML во время загрузки.Instead, missing or nonunique x:Key values cause load-time XAML parser errors. Однако обработка словарей для WPF в Visual Studio часто может зазаметить такие ошибки на этапе проектирования.However, Visual Studio handling of dictionaries for WPF can often note such errors in the design phase.

Обратите внимание, что в приведенном синтаксисе объект ResourceDictionary является неявным в том, как обработчик XAML WPF создает коллекцию для заполнения коллекции Resources.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. ResourceDictionary обычно не предоставляется явным образом как элемент в разметке, хотя в некоторых случаях это может быть, если бы это было необходимо для ясности (это будет элемент объекта коллекции между Resourcesным элементом свойства и элементами, заполняемыми в словаре).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). Сведения о том, почему объект коллекции почти всегда является неявным элементом в разметке, см. в разделе Подробное описание синтаксиса XAML.For information about why a collection object is almost always an implicit element in markup, see XAML Syntax In Detail.

В реализации XAML в WPF обработка ключей словаря ресурсов определяется ResourceKey абстрактным классом.In the WPF XAML implementation, the handling for resource dictionary keys is defined by the ResourceKey abstract class. Однако обработчик XAML WPF создает различные базовые типы расширений для ключей на основе их использования.However the WPF XAML processor produces different underlying extension types for keys based on their usages. Например, ключ для DataTemplate или любого производного класса обрабатывается отдельно и создает отдельный объект DataTemplateKey.For example, the key for a DataTemplate or any derived class is handled separately, and produces a distinct DataTemplateKey object.

Ключи и имена используют разные директивы и языковые элементы (x:Key и x:Name) в базовом определении XAML.Keys and names use different directives and language elements (x:Key versus x:Name) in the basic XAML definition. Ключи и имена также используются в различных ситуациях определения WPF и применения этих концепций.Keys and names are also used in different situations by the WPF definition and application of these concepts. Дополнительные сведения см. в разделе области имен XAML WPF.For details, see WPF XAML Namescopes.

Как упоминалось ранее, значение ключа можно передать с помощью расширения разметки и может быть отличным от строкового значения.As stated previously, the value of a key can be supplied through a markup extension and can be other than a string value. Примером сценария WPF является то, что значение x:Key может быть ComponentResourceKey.An example WPF scenario is that the value of x:Key may be a ComponentResourceKey. Некоторые элементы управления предоставляют ключ стиля этого типа для пользовательского ресурса стиля, который влияет на часть внешнего вида и поведения этого элемента управления без полной замены стиля.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. Примером такого ключа является ButtonStyleKey.An example of such a key is ButtonStyleKey.

Функция объединенного словаря WPF предоставляет дополнительные рекомендации по уникальности ключа и ведению поиска ключей.The WPF merged dictionary feature introduces additional considerations for key uniqueness and key lookup behavior. Подробнее см. в разделе Объединенные словари ресурсов.For more information, see Merged Resource Dictionaries.

XAML 2009XAML 2009

XAML 2009 ослабляет ограничение, которое x:Key всегда предоставляется в форме атрибута.XAML 2009 relaxes the restriction that x:Key always be provided in attribute form.

В WPF можно использовать функции XAML 2009, но только для XAML, который не является компилированной разметкой.In WPF, you can use XAML 2009 features, but only for XAML that is not markup-compiled. Скомпилированный с разметкой XAML и форма BAML кода XAML в настоящее время не поддерживают ключевые слова и компоненты XAML 2009.Markup-compiled XAML for WPF and the BAML form of XAML do not currently support the XAML 2009 keywords and features.

В XAML 2009 можно указать элементы x:Key с помощью следующих средств:Under XAML 2009, you can specify x:Key elements through the following usage:

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

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

Значения XAMLXAML Values

keyObject Объектный элемент для объекта, который используется в качестве ключа для данного object в специализированном словаре.Object element for the object that is used as the key for a given object in a specialized dictionary.
  • Контейнер/родитель для этого типа использования не показан здесь.The container/parent for this kind of use is not shown here. Ожидается, object является дочерним по отношению к элементу объекта, который представляет реализацию специализированного словаря.object is expected to be a child of an object element that represents a specialized dictionary implementation. Предполагается, что keyObject является экземпляром объекта (или значением типа значения), подходящим в качестве ключа для конкретной реализации специализированного словаря.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 не реализует словари, требующие такого использования.WPF does not implement dictionaries that require this usage. Объектные ключи — это более общий компонент языка XAML, который, возможно, полезен для некоторых сценариев пользовательских словарей, где желательно создать словарь в XAML.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. Для функций WPF, таких как неявные стили, которые используют Нестроковые ключи для ресурсов, существуют другие методы для установки или указания ключей, поэтому использование ключа объекта не требуется.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 could also be a markup extension usage in object element form, rather than a direct object instance.

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

x:Key для Silverlight задокументирована отдельно.x:Key for Silverlight is documented separately. Дополнительные сведения см. в разделе пространство имен XAML (x:). Функции языка (Silverlight).For more information, see XAML Namespace (x:) Language Features (Silverlight).

См. такжеSee also