x:Key 指令

  • 项目

对在 XAML 定义的字典中创建和引用的元素进行唯一标识。 向 XAML 对象元素添加 x:Key 值是标识资源字典（例如 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 值

值 说明
stringKeyValue 用作键的文本字符串。 文本字符串必须符合 XamlName 语法。
markupExtensionUsage 位于标记扩展分隔符 {} 中，一种标记扩展用法，提供用作键的对象。 请参阅“备注”。

备注

x:Key 支持 XAML 资源字典概念。 XAML 作为一种语言并未定义资源字典实现，该实现留给特定的 UI 框架。 若要详细了解如何在 WPF 中实现 XAML 资源字典，请参阅 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 的键。 例如，当通过代码将资源添加到 WPF 的 ResourceDictionary 中时，应用于 WPF 中的资源标记中的 x:Key 等效于 ResourceDictionary.Add 的 key 参数值。

WPF 用法注释

作为 IDictionary 实现的父对象的子对象（例如 WPF ResourceDictionary）通常必须包含 x:Key 属性，并且键值在该字典中必须是唯一的。 有两个值得注意的例外：

在整个 WPF XAML 实现和应用模型中，XAML 标记编译器不会检查键的唯一性。 相反，x:Key 值缺少或不唯一会导致加载时 XAML 分析器错误。 但是，Visual Studio 在处理 WPF 的字典时，通常会在设计阶段注意到此类错误。

请注意，在所示语法中，ResourceDictionary 对象在 WPF XAML 处理器生成集合来填充 Resources 集合的方式上是隐式的。 ResourceDictionary 通常不会作为标记中的元素显式提供，但在某些情况下，为了清楚起见可以显式提供（它将是 Resources 属性元素和填充字典的项之间的集合对象元素）。 有关为何集合对象几乎总是标记中的隐式元素的信息，请参阅 XAML 语法详细信息。

在 WPF XAML 实现中，对资源字典键的处理由 ResourceKey 抽象类定义。 但是，WPF XAML 处理器会根据其用途为键生成不同的基础扩展类型。 例如，DataTemplate 或任何派生类的键是单独处理的，并生成不同的 DataTemplateKey 对象。

键和名称在基本 XAML 定义中使用不同的指令和语言元素（x:Key 与 x:Name）。 WPF 定义和应用这些概念时，也会在不同情况下使用键和名称。 有关详细信息，请参阅 WPF XAML 名称范围。

如前所述，键的值可以通过标记扩展提供，并且可以不是字符串值。 一个示例 WPF 场景是 x:Key 的值可能是 ComponentResourceKey。 某些控件针对自定义的样式资源公开了该类型的样式键，该样式键会影响该控件的部分外观和行为，但不会完全替换样式。 此类键的一个示例是 ButtonStyleKey。

WPF 合并字典功能引入了有关键唯一性和键查找行为的其他注意事项。 有关详细信息，请参阅合并资源字典。

XAML 2009

XAML 2009 放松了 x:Key 始终以属性形式提供的限制。

在 WPF 中，可以使用 XAML 2009 功能，但仅针对未进行标记编译的 XAML。 WPF 的已编译标记的 XAML 以及 XAML 的 BAML 形式当前不支持 XAML 2009 关键字和功能。

在 XAML 2009 下，可以通过以下用法指定 x:Key 元素：

XAML 元素用法（仅 XAML 2009）

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

XAML 值

值 说明
keyObject 对象的 Object 元素，用作专用字典中给定 object 的键。

  • 具有此用途的容器/父级未在此处显示。 object 应该是表示专用字典实现的 Object 元素的子元素。 keyObject 应该是一个对象实例（或值类型的值），它适合作为特定专用字典实现的键。

  • WPF 不会实现要求此用法的字典。 对象键更像是 XAML 语言的一般功能，可能对某些自定义字典方案（其中需要在 XAML 中创建字典）有用。 对于 WPF 功能（例如，对资源使用非字符串键的隐式样式），还存在其他用于建立或指定键的技术，因此不需要使用对象键。

  • keyObject 也可以是采用对象元素形式的标记扩展用法，而不是直接的对象实例。

Silverlight 使用注意事项

单独记录了 Silverlight 的 x:Key。 有关详细信息，请参阅 XAML 命名空间 (x:) 语言功能 (Silverlight)。

另请参阅