x:Name 指令

唯一标识 XAML 名称范围中 XAML 定义的元素。 当框架提供 API 或实现在运行时访问 XAML 创建的对象图的行为时,XAML 名称范围及其唯一性模型可以应用于实例化对象。

XAML 属性用法

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

XAML 值

价值 描述
XAMLNameValue 符合 XamlName 语法限制的字符串。

言论

x:Name 应用于框架的后备编程模型后,该名称等效于保存对象引用或构造函数返回的实例的变量。

x:Name 指令用法的值在 XAML 名称范围中必须是唯一的。 默认情况下,当 .NET XAML 服务 API 使用时,主 XAML 名称范围是在单个 XAML 生产的 XAML 根元素上定义的,并包含该 XAML 生产中包含的元素。 单个 XAML 生产中可能发生的其他离散 XAML 名称范围可由框架定义,以解决特定方案。 例如,在 WPF 中,新的 XAML 名称范围由任何也在该 XAML 生产中定义的模板定义和创建。 有关 XAML 名称范围(为 WPF 编写但与许多 XAML 名称范围概念相关)的详细信息,请参阅 WPF XAML 名称范围

通常,在也使用 x:Key的情况下,不应应用 x:Name。 特定现有框架的 XAML 实现在 x:Keyx:Name之间引入了替换概念,但这不是建议的做法。 处理名称/密钥信息(如 INameScopeDictionaryKeyPropertyAttribute)时,.NET XAML 服务不支持此类替换概念。

允许 x:Name 的规则以及名称唯一性强制执行的规则可能由特定的实现框架定义。 但是,若要与 .NET XAML 服务一起使用,XAML 名称范围唯一性的框架定义应与本文档中 INameScope 信息的定义一致,并且应使用与应用信息的位置相同的规则。 例如,Windows Presentation Foundation (WPF) 实现将各种标记元素划分为单独的 NameScope 范围,例如资源字典、由页面级 XAML、模板和其他延迟内容创建的逻辑树,然后在其中每个 XAML 名称范围中强制实施 XAML 名称唯一性。

对于使用 .NET XAML 服务 XAML 对象编写器的自定义类型,可以建立或更改映射到类型上的 x:Name 的属性。 通过引用要与类型定义代码中的 RuntimeNamePropertyAttribute 映射的属性的名称来定义此行为。 RuntimeNamePropertyAttribute 是类型级属性。

Using.NET XAML 服务,可以通过实现 INameScope 接口,以中性的方式定义 XAML 名称范围支持的后备逻辑。

WPF 用法说明

在使用 XAML、分部类和代码隐藏的 WPF 应用程序的标准生成配置下,指定的 x:Name 将成为由标记编译生成任务处理 XAML 时在基础代码中创建的字段的名称,并且该字段包含对对象的引用。 默认情况下,创建的字段为内部字段。 可以通过指定 x:FieldModifier 属性来更改字段访问权限。 在 WPF 和 Silverlight 中,序列是标记编译定义并命名分部类中的字段,但值最初为空。 然后,从类构造函数中调用名为 InitializeComponent 的生成的方法。 InitializeComponentFindName 调用组成,这些调用使用分部类中 XAML 定义的部分存在的每个 x:Name 值作为输入字符串。 然后,将返回值分配给类似命名的字段引用,以使用从 XAML 分析创建的对象填充字段值。 InitializeComponent 的执行使你能够直接使用 x:Name/字段名称引用运行时对象图,而无需在需要引用 XAML 定义的对象时显式调用 FindName

对于使用 Microsoft Visual Basic 目标的 WPF 应用程序,并且包含具有 Page 生成操作的 XAML 文件,编译期间会创建单独的引用属性,该属性将 WithEvents 关键字添加到具有 x:Name的所有元素,以支持事件处理程序委托的 Handles 语法。 此属性始终为公共属性。 有关详细信息,请参阅 Visual Basic 和 WPF 事件处理

WPF XAML 处理器使用 x:Name 在加载时将名称注册到 XAML 名称范围,即使没有通过生成操作(例如资源字典的松散 XAML)编译页面也是如此。 此行为的原因之一是 ElementName 绑定可能需要 x:Name。 有关详细信息,请参阅 数据绑定概述

如前所述,在也使用 x:Key的情况下,不应应用 x:Name(或 Name)。 WPF ResourceDictionary 具有一种特殊行为,即将自身定义为 XAML 名称范围,但返回 INameScope API 的未实现或 null 值作为强制实施此行为的方法。 如果 WPF XAML 分析程序在 XAML 定义的 ResourceDictionary中遇到 Namex:Name,则名称不会添加到任何 XAML 名称范围。 尝试从任何 XAML 名称范围查找该名称,FindName 方法将不会返回有效结果。

x:Name and Name

许多 WPF 应用程序方案可以避免使用 x:Name 属性,因为 Name 依赖属性在默认 XAML 命名空间中指定的几个重要基类(如 FrameworkElementFrameworkContentElement 满足此相同目的)。 在框架级别没有 Name 属性的元素的代码访问仍存在一些常见的 XAML 和 WPF 方案。 例如,某些动画和情节提要支持类不支持 Name 属性,但它们通常需要在代码中引用才能控制动画。 如果要稍后从代码引用它们,则应将 x:Name 指定为时间线和 XAML 中创建的转换的属性。

如果 Name 可用作类上的属性,则可以将 Namex:Name 互换用作属性,但如果两者都在同一元素上指定,则分析异常将产生。 如果 XAML 已编译标记,则异常将在标记编译上发生,否则会在加载时发生。

可以使用 XAML 属性语法设置 Name,在代码中使用 SetValue;但请注意,在代码中设置 Name 属性不会在已加载 XAML 的大多数情况下在 XAML 名称范围中创建具有代表性的字段引用。 不要尝试在代码中设置 Name,而是针对相应的名称范围使用代码中的 NameScope 方法。

也可以使用具有内部文本的属性元素语法设置 Name,但这种情况并不常见。 相比之下,不能在 XAML 属性元素语法或使用 SetValue; 的代码中设置 x:Name;它只能对对象使用属性语法进行设置,因为它是指令。

Silverlight 用法说明

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

另请参阅