FrameworkElement.Name 属性

定义

获取或设置 对象的标识名称。 当 XAML 处理器从 XAML 标记创建对象树时,运行时代码可以按此名称引用 XAML 声明的对象。

public:
 property Platform::String ^ Name { Platform::String ^ get(); void set(Platform::String ^ value); };
winrt::hstring Name();

void Name(winrt::hstring value);
public string Name { get; set; }
var string = frameworkElement.name;
frameworkElement.name = string;
Public Property Name As String
<frameworkElement Name="xamlNameString"/>

属性值

String

Platform::String

winrt::hstring

对象的名称,该名称必须是在 XamlName 语法中有效的字符串 (请参阅 x:Name 属性 引用) 中的表。 默认值为空字符串。

示例

此示例从现有 对象获取 的值 Name ,并使用该名称重新定位动画。 通过设置 Storyboard.TargetName 附加属性来设定动画的目标。

private void Start_Animation(object sender, PointerRoutedEventArgs e)
{

    // If the Storyboard is running and you try to change
    // properties of its animation objects programmatically, 
    // an error will occur.
    myStoryboard.Stop();

    // Get a reference to the rectangle that was clicked.
    Rectangle myRect = (Rectangle)sender;

    // Change the TargetName of the animation to the name of the
    // rectangle that was clicked.
    myDoubleAnimation.SetValue(Storyboard.TargetNameProperty, myRect.Name);

    // Begin the animation.
    myStoryboard.Begin();
}

注解

此属性的最常见用法是在 XAML 标记中为对象指定 x:Name 属性 ,或者在标记中设置该值时读取该值。 在大多数方面, x:Name 属性和 Name 属性是等效的。 在任何单个元素上 x:Name , 属性和 Name 属性作为 XAML 属性相互排斥;如果尝试在标记中的同一对象元素上同时 x:Name 设置 和 Name ,将引发分析程序错误。

对 XAML 使用默认 的 Page 生成操作时,任何具有 x:Name 属性Name 生成字段引用的任何 XAML 元素都会在加载 XAML 时最终填充 InitializeComponent 这些引用。 字段引用启用编程模型,一旦 XAML 对象树加载到页面或应用中,就可以在特定于页面的代码隐藏中按名称直接引用对象。

名称在 XAML 名称范围中必须是唯一的。 通常,XAML 名称范围由 XAML 页面定义,但某些功能(如模板或对 API 的调用(如 XamlReader.Load )可以定义单独的 XAML 名称范围。 有关详细信息,请参阅 XAML 空间范围

Name 永远不应本地化。 Name 用作代码隐藏中的字段名称变量。 本地化人员通常无法访问此类代码,否则他们可能有权访问定义 UI 的 XAML 文件,尽管这取决于你的部署模型和本地化过程。 这是你不应在应用 UI 中显示来自名称的任何字符串的原因之一。

名称方案

在定义 UI 元素的 XAML 中设置 x:NameName 支持多种主要方案:

  • 动画目标 若要将动画应用于对象属性,必须以特定实例为目标。 可通过在任何时间线上设置 Storyboard.TargetName 附加属性来执行此操作。 此处设置的值是分配为 或 Namex:Name字符串。 有关详细信息,请参阅情节提要动画
  • 控件模板的各个部分 为了支持可视状态模型和控件初始化,控件作者应为模板化控件的关键部分指定 Name 值。 有关详细信息,请参阅 XAML 控件模板
  • 常规运行时交互 例如,事件处理程序中的代码可能会处理提供更改 UI 的对象上的事件,但对属性的更改发生在另一个附近的 UI 元素上。 针对这种情况编写代码的最简单方法是使用从 Name生成的字段引用。

FindName

可从任何 FrameworkElement 获取的实用工具方法 FindName 可以在对象树中按名称查找对象,只要它们位于当前 XAML 名称范围中。 FindName 完整搜索 XAML 创建的对象树。 从技术上讲,实际搜索的是 FindName XAML 名称范围,它不保留树隐喻,而是表示为名称的哈希表。 FindName 找不到应用模板中定义的名称。 若要查找已应用模板中的项,请使用 VisualTreeHelper.GetChild 获取已应用的模板根对象。 然后,可以针对该根对象调用 FindName ,你将搜索模板的 XAML 名称范围,而不是更大的页面。

名称和数据绑定

不能将 的 Name 字符串值用作数据绑定源的直接源值。 如果必须显示与在具有绑定的 UI 中相同的字符串值 Name ,则应将相同的值复制到 Tag 属性,该属性可用作属性绑定源。 也不要将 Name 用作绑定目标。

Name 的值x:Name是用于标识 ElementName 绑定的源元素的标识符。 有关详细信息,请参阅 深入的数据绑定

在代码中设置名称

可以在运行时为 对象设置 的值 Name ,但应注意一些重要的注意事项和限制。

如果对象以前Name在 XAML 中设置了值Name,则通常不建议在运行时在代码中更改 的值。 这是因为在加载对象树后设置名称不会创建或更改等效字段引用的标识名称。 如果字段引用已存在,因为 x:Name 在初始标记中提供了 ,并且你更改 的值 Name,则字段和通过 FindName 查找对象所需的名称现在将有所不同,因为该字段仍保留为标记定义的名称。

Name为在代码中创建的对象设置值,因此从未具有 XAML 定义的 Name 值适用于某些方案。 其中一种情况是,如果希望能够通过使用 FindName 作为常用实用工具函数,在树中查找 XAML 创建的对象或代码创建的对象。 为了使该方案正常工作,Windows 运行时在运行时继续使用并添加到 XAML 名称范围哈希表表示形式。 如果尝试将新的命名对象添加到主要由 XAML 创建的现有对象树,则名称必须唯一,否则会发生重复的名称异常。 尝试设置 Name时,可能不会发生重复名称异常。 在尝试将重复命名的对象添加到main对象树之前,新对象具有其自己的自包含 XAML 名称范围。 只有在将对象连接到更大的对象树时,才能检测到重复的名称条件。 或者,在连接树中的对象的操作上可能发生异常,例如,在调用Add连接到main对象树的集合的 方法时。

可能很难知道 XAML 名称范围中已存在哪些 Name 值,稍后将向其添加新对象。 没有特定的 API 报告 XAML 名称范围中现有名称的完整哈希表。 如果在代码中广泛设置 Name 值,则可能需要一种技术来生成对运行时使用情况唯一的名称字符串,或者可能需要将新命名对象的调用包装在 try-catch 块中,以捕获可能由重复名称导致的异常。 或者,可以将自己的代码添加到 InitializeComponent 读取 XAML 生成的名称值的实现中。

请注意,只能在运行时为 FrameworkElementInline 的对象设置Name。 如果对象没有 Name 属性,并且需要使用 x:Name 属性而不是 Name在 XAML 中设置名称,则没有可用于设置此类对象的运行时名称的运行时 API。

适用于

另请参阅