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:Name 应用于同时使用 x:Key 的情况。 特定现有框架的 XAML 实现在 x:Key 和 x:Name 之间引入了替换概念，但不建议这样做。 .NET XAML 服务在处理名称/键信息（例如 INameScope 或 DictionaryKeyPropertyAttribute）时不支持此类替换概念。

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

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

使用 .NET XAML 服务，XAML 名称范围支持的支持逻辑可通过实现 INameScope 接口以与框架无关的方式定义。

WPF 用法注释

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

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

WPF XAML 处理器使用 x:Name 在加载时将名称注册到 XAML 名称范围，即使在页面不是由生成操作进行标记编译的情况下（例如，资源字典的松散 XAML）也是如此。 出现这种行为的一个原因是，ElementName 绑定可能需要 x:Name。 有关详细信息，请参阅数据绑定概述。

如前所述，不应将 x:Name（或 Name）应用于同时使用 x:Key 的情况。 WPF ResourceDictionary 具有一种特殊行为，即将自己定义为 XAML 名称范围，但为 INameScope API 返回未实现或 NULL 值，作为强制执行此行为的一种方式。 如果 WPF XAML 分析程序在 XAML 定义的 ResourceDictionary 中遇到 Name 或 x:Name，则不会将该名称添加到任何 XAML 名称范围。。 如果尝试从任何 XAML 名称范围和 FindName 方法中查找该名称，则将不会返回有效结果。

x:Name 和 Name

许多 WPF 应用程序场景可避免使用任何 x:Name 属性，因为在默认 XAML 命名空间中为几个重要的基类（例如 FrameworkElement 和 FrameworkContentElement）指定的 Name 依赖项属性满足这一目的。 仍存在一些常见的 XAML 和 WPF 场景，其中代码访问在框架级别没有 Name 属性的元素非常重要。 例如，某些动画和情节提要支持类不支持 Name 属性，但通常需要在代码中引用这些属性才能控制动画。 如果打算稍后从代码中引用它们，则应将 x:Name 指定为在 XAML 中创建的时间线和转换的属性。

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

可使用 XAML 属性语法和在代码中使用 SetValue 来设置 Name；但请注意，在已加载 XAML 的大多数情况下，在代码中设置 Name 属性不会在 XAML 名称范围内创建代表性字段引用。 不要尝试在代码中设置 Name，请改为针对适当的名称范围使用代码中的 NameScope 方法。

也可使用带有内部文本的属性元素语法来设置 Name，但这并不常见。 与此相反，不能在 XAML 属性元素语法或在代码中使用 SetValue 来设置 x:Name；由于它是一个指令，因此只能使用对象的属性语法对其进行设置。

Silverlight 使用注意事项

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

另请参阅