x:Name 属性x:Name attribute

唯一标识对象元素,可方便从代码隐藏或一般代码中访问已实例化的对象。Uniquely identifies object elements for access to the instantiated object from code-behind or general code. 应用于支持的编程模型之后,x:Name 可视为等效于持有一个对象引用(由一个构造函数返回)的变量。Once applied to a backing programming model, x:Name can be considered equivalent to the variable holding an object reference, as returned by a constructor.

XAML 属性使用方法XAML attribute usage

<object x:Name="XAMLNameValue".../>

XAML 值XAML values

术语Term 描述Description
XAMLNameValueXAMLNameValue 一个符合 XamlName 语法限制的字符串。A string that conforms to the restrictions of the XamlName grammar.

XamlName 语法XamlName grammar

以下是在此 XAML 实现中作为密钥使用的字符串的规范语法:The following is the normative grammar for a string that is used as a key in this 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. 如果用户将数字作为初始字符提供,则某些工具实现会将下划线 (_) 添加到字符串,或者工具会根据包含数字的其他值自动生成 x:Name 值。Some tool implementations prepend an underscore (_) to a string if the user supplies a digit as the initial character, or the tool autogenerates x:Name values based on other values that contain digits.


当处理 XAML 时,指定的 x:Name 变成一个在基础代码中创建的字段的名称,该字段持有该对象的引用。The specified x:Name becomes the name of a field that is created in the underlying code when XAML is processed, and that field holds a reference to the object. 创建此字段的过程由 MSBuild 目标步骤执行,这些步骤还负责连接一个 XAML 文件和它的代码隐藏的分部类。The process of creating this field is performed by the MSBuild target steps, which also are responsible for joining the partial classes for a XAML file and its code-behind. 此行为不一定是由 XAML 语言指定的,它是通用 Windows 平台 (UWP) XAML 编程的特定实现,应用在其编程和应用程序模型中使用 x:NameThis behavior is not necessarily XAML-language specified; it is the particular implementation that Universal Windows Platform (UWP) programming for XAML applies to use x:Name in its programming and application models.

每个已定义的 x:Name 在一个 XAML 名称范围中必须是唯一的。Each defined x:Name must be unique within a XAML namescope. 通常,XAML 名称范围在所加载页面的根元素级别定义,其中包含单个 XAML 页面中该元素下面的所有元素。Generally, a XAML namescope is defined at the root element level of a loaded page and contains all elements under that element in a single XAML page. 其他 XAML 名称范围由在该页面上定义的任何控件模板或数据模板定义。Additional XAML namescopes are defined by any control template or data template that is defined on that page. 在运行时,其他 XAML 名称范围是为从所应用的控件模板创建的对象树的根,以及由从 XamlReader.Load 调用创建的对象树定义的。At run time, another XAML namescope is created for the root of the object tree that is created from an applied control template, and also by object trees created from a call to XamlReader.Load. 有关详细信息,请参阅 XAML 空间范围For more info, see XAML namescopes.

在将元素引入设计界面时,设计工具常常会自动为它们生成 x:Name 值。Design tools often autogenerate x:Name values for elements when they are introduced to the design surface. 该自动生成架构因使用的设计器不同而不同,但一种典型的架构是生成一个字符串,它以支持该元素的类名开头,后跟一个延长的整数。The autogeneration scheme varies depending on which designer you are using, but a typical scheme is to generate a string that starts with the class name that backs the element, followed by an advancing integer. 例如,如果向设计器引入第一个 Button 元素,则可以在 XAML 中看到,此元素拥有 x:Name 属性值“Button1”。For example, if you introduce the first Button element to the designer, you might see that in the XAML this element has the x:Name attribute value of "Button1".

无法在 XAML 属性元素语法中或在代码中使用 SetValue 设置 x:Namex:Name cannot be set in XAML property element syntax, or in code using SetValue. 只能在元素上使用 XAML 属性语法来设置 x:Namex:Name can only be set using XAML attribute syntax on elements.

注意   专用于 c + +/CX 应用,不会为 XAML 文件或页面的根元素创建x:Name引用的支持字段。Note  Specifically for C++/CX apps, a backing field for an x:Name reference is not created for the root element of a XAML file or page. 如果你需要从 C++ 代码隐藏来引用根对象,请使用其他 API 或树形遍历。If you need to reference the root object from C++ code-behind, use other APIs or tree traversal. 例如,你可以为已知的命名子元素调用 FindName,然后调用 ParentFor example you can call FindName for a known named child element and then call Parent.

x:Name 和其他 Name 属性x:Name and other Name properties

UWP XAML 中使用的一些类型还具有一个名为 Name 的属性。Some types used in UWP XAML also have a property named Name. 例如,FrameworkElement.NameTextElement.NameFor example, FrameworkElement.Name and TextElement.Name.

如果 Name 可用作一个元素上的可设置属性,Namex:Name 可在 XAML 中交替使用,但如果在相同元素上指定了这两个属性,会发生错误。If Name is available as a settable property on an element, Name and x:Name can be used interchangeably in XAML, but an error results if both attributes are specified on the same element. 有时,会存在一个只读的 Name 属性(如 VisualState.Name)。There are also cases where there's a Name property but it's read-only (like VisualState.Name). 如果出现这种情况,请在 XAML 中始终使用 x:Name 对该元素进行命名,而且对于一些少见的代码方案使用只读的 NameIf that's the case you always use x:Name to name that element in the XAML and the read-only Name exists for some less-common code scenario.

注意  FrameworkElement.Name 通常不应当用于更改最初由 x:Name 设置的值,但这个一般规则有一些例外的场景。Note  FrameworkElement.Name generally should not be used as a way to change values originally set by x:Name, although there are some scenarios that are exceptions to that general rule. 在典型的场景中,XAML 名称范围的创建和定义是一个 XAML 处理器操作。In typical scenarios, the creation and definition of XAML namescopes is a XAML processor operation. 在运行时修改 FrameworkElement.Name 可能会导致不一致的 XAML 名称范围/专用字段命名对齐,这种不一致在代码隐藏文件中很难跟踪。Modifying FrameworkElement.Name at run time can result in an inconsistent XAML namescope / private field naming alignment, which is hard to keep track of in your code-behind.

x:Name 和 x:Keyx:Name and x:Key

x:Name 可以作为一个属性应用到 ResourceDictionary 内的元素,以充当 x:Key 属性的替代属性。x:Name can be applied as an attribute to elements within a ResourceDictionary to act as a substitute for the x:Key attribute. (通常,要求 ResourceDictionary 中的所有元素都必须具有一个 x:Key 或 x:Name 属性。)这常见于情节提要动画(It's a rule that all elements in a ResourceDictionary must have an x:Key or x:Name attribute.) This is common for Storyboarded animations. 有关详细信息,请参阅 ResourceDictionary 和 XAML 资源引用部分。For more info, see section of ResourceDictionary and XAML resource references.