FrameworkElement.Name 属性

定义

命名空间:

Windows.UI.Xaml

获取或设置对象的标识名称。 当 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();
}

Private Sub Start_Animation(ByVal sender As Object, ByVal e As PointerRoutedEventArgs)
    ' 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.
    Dim myRect As Rectangle = CType(sender, Rectangle)
    ' 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()
End Sub

注解

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

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

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

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

名称方案

在定义 UI 元素的 XAML 中设置 x：Name 或 Name 支持以下几种主要方案：+ 动画目标 若要将动画应用于对象属性，必须面向特定实例。 为此，可以在任何时间线上设置 Storyboard.TargetName 附加属性。 此处设置的值是分配为 x：Name 或 Name 的字符串。 有关详细信息，请参阅情节提要动画。

• 控件模板的各个部分 为了支持可视状态模型和控件初始化，控件作者应为模板化控件的关键部分指定 Name 值。 有关详细信息，请参阅 快速入门：控件模板。
• 常规运行时交互 例如，事件处理程序中的代码可能会处理提供更改 UI 的对象上的事件，但对属性的更改发生在另一个附近的 UI 元素上。 针对这种情况编写代码的最简单方法是使用从 Name 生成的字段引用。

FindName

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

名称和数据绑定

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

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

在代码中设置名称

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

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

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

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

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

另请参阅

• FindName(String)
• x:Name 属性
• Storyboard.TargetName
• XAML 名称范围
• XAML概述