x:Key 特性x:Key attribute

唯一标识作为资源被创建和引用的元素,这些资源存在于一个 ResourceDictionary 中。Uniquely identifies elements that are created and referenced as resources, and which exist within a ResourceDictionary.

XAML 属性使用方法XAML attribute usage

<ResourceDictionary>
  <object x:Key="stringKeyValue".../>
</ResourceDictionary>

XAML 属性使用方法(隐式 ResourceDictionaryXAML attribute usage (implicit ResourceDictionary)

<object.Resources>
  <object x:Key="stringKeyValue".../>
</object.Resources>

XAML 值XAML values

术语Term 描述Description
对象 (object)object 任何可共享的对象。Any object that is shareable. 请参阅 ResourceDictionary 和 XAML 资源引用See ResourceDictionary and XAML resource references.
stringKeyValuestringKeyValue 一个用作键的真实字符串,它必须遵守 XamlName> 语法。A true string used as a key, which must conform to the XamlName> grammar. 请参阅下面的“XamlName 语法”。See "XamlName grammar" below.  

XamlName 语法XamlName grammar

以下是在通用 Windows 平台 (UWP) XAML 实现中作为键使用的字符串的规范语法:The following is the normative grammar for a string that is used as a key in the Universal Windows Platform (UWP) XAML implementation:

XamlName ::= NameStartChar (NameChar)*
NameStartChar ::= LetterCharacter | '_'
NameChar ::= NameStartChar | DecimalDigit
LetterCharacter ::= ('a'-'z') | ('A'-'Z')
DecimalDigit ::= '0'-'9'
CombiningCharacter::= none
  • 字符限制为较小的 ASCII 范围,更专用于罗马字母大写和小写字母、数字和下划线 (_) 字符。Characters are restricted to the lower ASCII range, and more specifically to Roman alphabet uppercase and lowercase letters, digits, and the underscore (_) character.
  • 不支持 Unicode 字符范围。The Unicode character range is not supported.
  • 名称不能以数字开头。A name cannot begin with a digit.

备注Remarks

ResourceDictionary 的子元素一般包含一个 x:Key 属性,该属性在该词典中指定一个唯一的键值。Child elements of a ResourceDictionary generally include an x:Key attribute that specifies a unique key value within that dictionary. 键唯一性在加载时由 XAML 处理器执行。Key uniqueness is enforced at load time by the XAML processor. 非唯一的 x:Key 值将导致 XAML 分析异常。Non-unique x:Key values will result in XAML parse exceptions. 如果 {StaticResource} 标记扩展发出请求,任何未解析的键也会导致 XAML 分析异常。If requested by {StaticResource} markup extension, a non-resolved key will also result in XAML parse exceptions.

x:Keyx:Name 不是同一概念。x:Key and x:Name are not identical concepts. x:Key 仅用于资源词典中。x:Key is used exclusively in resource dictionaries. x:Name 适用于 XAML 的所有区域。x:Name is used for all areas of XAML. 一个使用键值的 FindName 调用不会检索键资源。A FindName call using a key value will not retrieve a keyed resource. 在资源字典中定义的对象可能有一个 x:Key、一个 x:Name 或两者皆有。Objects defined in a resource dictionary may have an x:Key, an x:Name or both. 不要求键和名称互相匹配。The key and name are not required to match.

请注意,在给出的隐式语法中,ResourceDictionary 对象在 XAML 处理器生成一个新对象来填充 Resources 集合的方式上是隐式的。Note that in the implicit syntax shown, the ResourceDictionary object is implicit in how the XAML processor produces a new object to populate a Resources collection.

指定 x:Key 的代码等效于任何结合使用一个键和基础 ResourceDictionary 的操作。The code equivalent of specifying x:Key is any operation that uses a key with the underlying ResourceDictionary. 例如,当向一个 ResourceDictionary 添加资源时,一个应用于资源标记中的 x:Key 等效于 Insertkey 参数的值。For example, an x:Key applied in markup for a resource is equivalent to the value of the key parameter of Insert when you add the resource to a ResourceDictionary.

如果资源字典中的某个项是目标 StyleControlTemplate,则它可以省略 x:Key 的值;在每一种情况下,该资源项的隐式键都是解释为字符串的 TargetType 值。An item in a resource dictionary can omit a value for x:Key if it is a targeted Style or ControlTemplate; in each of these cases the implicit key of the resource item is the TargetType value interpreted as a string. 有关详细信息,请参阅快速入门:设置控件的样式ResourceDictionary 和 XAML 资源引用For more info, see Quickstart: styling controls and ResourceDictionary and XAML resource references.