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

Уникально определяет элементы, которые создаются и ссылаются в словаре, определяемом XAML.Uniquely identifies elements that are created and referenced in a XAML-defined dictionary. Добавление x:Key значения к элементу объекта XAML является наиболее распространенным способом идентификации ресурса ResourceDictionaryв словаре ресурсов, например в WPF.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. Текстовая строка должна соответствовать грамматике XamlName.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 как язык не определяет реализацию словаря ресурсов, то есть остается за определенными инфраструктурами uI.XAML as a language doesn't define a resource dictionary implementation, that is left to specific UI frameworks. Чтобы узнать больше о том, как словари ресурсов XAML реализуются в WPF, см.To learn more about how XAML resource dictionaries are implemented in WPF, see XAML Resources.

В XAML 2006 и x:Key WPF, должны быть предоставлены в качестве атрибута.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 может быть любой строкой, определенной в грамматике XamlName или может быть объектом, оцениваемым с помощью расширения разметки.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 значение, применяемое в разметке ресурса в key WPF, эквивалентно значению параметра ResourceDictionary.Add при добавлении ресурса в WPF ResourceDictionary в коде.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 объекта, который является ResourceDictionaryреализацией, такие x:Key как WPF, должны обычно включать атрибут, и ключевое значение должно быть уникальным в этом словаре.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.

В общей модели внедрения и применения WPF XAML уникальность ключей не проверяется компилятором разметки 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. Тем не менее, Visual Studio обработки словарей для WPF часто можно отметить такие ошибки на этапе проектирования.However, Visual Studio handling of dictionaries for WPF can often note such errors in the design phase.

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

В реализации WPF XAML обработка ключей словаря ResourceKey ресурсов определяется абстрактным классом.In the WPF XAML implementation, the handling for resource dictionary keys is defined by the ResourceKey abstract class. Однако процессор WPF XAML производит различные базовые типы расширений для ключей в зависимости от их использования.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. Для получения подробной информации см.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 в том, что значение может быть компонентомResourceKey.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также может быть использование расширения разметки в форме элемента объекта, а не экземпляр прямого объекта.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. Для получения дополнительной информации см. Языковые особенности (Silverlight).For more information, see XAML Namespace (x:) Language Features (Silverlight).

См. такжеSee also