x:Key 指令x:Key Directive

唯一标识在 XAML 定义的字典中创建和引用的元素。Uniquely identifies elements that are created and referenced in a XAML-defined dictionary. x:Key在 XAML 对象元素中添加值是在资源字典中标识资源的最常见方法,例如在 WPF 中 ResourceDictionaryAdding 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.

XAML 属性用法XAML 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>  

XAML 值XAML 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. 若要了解有关如何在 WPF 中实现 XAML 资源字典的详细信息,请参阅 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 可以是 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 ; 定义此类属性的类型应采用特性化 DictionaryKeyPropertyAttributeFrameworks 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 是用于基础的键 IDictionaryThe code equivalent of specifying x:Key is the key that is used for the underlying IDictionary. 例如, x:Key key ResourceDictionary.Add 当你在代码中将资源添加到 wpf 时,适用于 wpf 中某个资源的标记的将与的参数的值等效 ResourceDictionaryFor 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.

WPF 用法说明WPF Usage Notes

IDictionary作为实现(如 WPF)的父对象的子对象 ResourceDictionary 通常必须包含 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 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 for WPF 字典处理通常会在设计阶段记录此类错误。However, Visual Studio handling of dictionaries for WPF can often note such errors in the design phase.

请注意,在显示的语法中, ResourceDictionary 对象是隐式的,因为 WPF XAML 处理器如何生成用于填充 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.

在 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. 有关详细信息,请参阅 WPF XAML 名称范围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 可以是 ComponentResourceKeyAn 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. 此类键的一个示例是 ButtonStyleKeyAn 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. WPF 的已编译标记的 XAML 以及 XAML 的 BAML 形式当前不支持 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>  

XAML 值XAML Values

keyObject 对象的对象元素,该对象用作专用字典中给定的的键 objectObject 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.

Silverlight 使用说明Silverlight 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