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

Чаще всего это свойство используется для указания атрибута x:Name для объекта в разметке XAML или для чтения этого значения так, как оно было задано в разметке. В большинстве случаев атрибут x:Name и свойство Name эквивалентны. В любом отдельном элементе атрибут x:Name и свойство Name являются взаимоисключающими как атрибуты XAML; При попытке задать x:Name и Name для одного и того же элемента объекта в разметке возникает ошибка средства синтаксического анализа.

При использовании действий сборки страницы по умолчанию для XAML любой элемент XAML с атрибутом x:Name или Name создает ссылки на поля, которые в конечном итоге заполняются InitializeComponent при загрузке XAML. Ссылки на поля позволяют создать модель программирования, в которой на объекты можно напрямую ссылаться по имени в коде программной части конкретной страницы после загрузки дерева объектов XAML на страницу или приложение.

Имена должны быть уникальными в области имен XAML. Как правило, область имен XAML определяется страницей XAML, но некоторые функции, такие как шаблоны или вызовы API, такие как XamlReader.Load , могут определять отдельные области имен XAML. Подробнее см. в разделе Области имен XAML.

Имя никогда не должно быть локализовано. Name используется в качестве переменной имени поля в коде программной части. Такой код обычно недоступен для локализатора, который в противном случае мог бы иметь доступ к XAML-файлам, определяющим пользовательский интерфейс, хотя это зависит от модели развертывания и процедур локализации. Это одна из причин, почему в пользовательском интерфейсе приложения не следует отображать строки, полученные из имени.

Сценарии для имени

Параметр x:Name или Name в XAML, определяющий элементы пользовательского интерфейса, поддерживает несколько основных сценариев: + Анимация нацеливание . Чтобы применить анимацию к свойству объекта, необходимо нацелиться на определенный экземпляр. Это можно сделать, задав присоединенное свойство Storyboard.TargetName на любой временной шкале. Здесь задано значение строки, назначенной в качестве x:Name или Name. Подробнее: Раскадрованные анимации.

Части шаблона элемента управления Чтобы обеспечить поддержку модели визуального состояния и инициализации элемента управления, авторы элементов управления должны указывать значения name для ключевых частей шаблонного элемента управления. Дополнительные сведения см. в статье Краткое руководство. Шаблоны элементов управления.
Взаимодействие с общим временем выполнения Например, код в обработчике событий может обрабатывать событие в объекте, который предоставляет пользовательский интерфейс изменения, но изменение свойств происходит в другом соседнем элементе пользовательского интерфейса. Самый простой способ написать код для этой ситуации — использовать ссылку на поле, созданную на основе имени.

FindName

Служебный метод FindName, доступный в любой платформе FrameworkElement, может находить объекты по имени в дереве объектов, если они находятся в текущей области имен XAML. FindName выполняет поиск в дереве объектов, созданном на XAML, в полном объеме. С технической точки зрения поиск FindName — это область имен XAML, которая не сохраняет метафору дерева и представляется в виде хэш-таблицы имен. FindName не может найти имена, определенные в примененных шаблонах. Чтобы найти элементы в примененных шаблонах, используйте VisualTreeHelper.GetChild , чтобы получить примененный корневой объект шаблона. Затем можно вызвать FindName для этого корневого объекта, и вы будете искать область имен XAML шаблона, а не большую страницу.

Привязка имени и данных

Строковое значение Name нельзя использовать в качестве значения прямого источника для источника привязки данных. Если необходимо отобразить то же строковое значение, что и Имя в пользовательском интерфейсе с привязкой, необходимо реплицировать то же значение в свойство Tag , которое можно использовать в качестве источника привязки свойства. Кроме того, не используйте Имя в качестве целевого объекта привязки.

Значение x:Name или Name — это идентификатор, используемый для идентификации исходного элемента привязки ElementName . Дополнительные сведения см. в разделе Привязка данных.

Имя параметра в коде

Вы можете задать значение Name для объекта во время выполнения, но есть некоторые важные рекомендации и ограничения, которые следует учитывать.

Изменение значения Name в коде во время выполнения, если для объекта было задано предыдущее значение Name в XAML, обычно не рекомендуется. Это связано с тем, что установка имени после загрузки дерева объектов не приведет к созданию или изменению идентифицирующего имени эквивалентной ссылки на поле. Если ссылка на поле уже существует, так как x:Name указана в начальной разметке и вы изменяете значение Name, поле и имя, которое необходимо использовать для поиска объекта с помощью FindName , теперь отличаются, так как поле остается в качестве имени, определяемого разметкой.

Задание значения Name для объекта, который был создан в коде и поэтому никогда не имел определенного xaml-значения Name, подходит для определенных сценариев. Один из таких сценариев — если вы хотите найти объекты, созданные xaml или кодом, в дереве с помощью FindName в качестве общей служебной функции. Чтобы этот сценарий работал, среда выполнения Windows продолжает использовать и добавлять в хэш-представление области имен XAML во время выполнения. При попытке добавить новые именованные объекты в существующее дерево объектов, в основном созданное XAML, имена должны быть уникальными, в противном случае возникнет исключение повторяющихся имен. Исключение повторяющегося имени может не возникнуть при попытке задать имя. Пока не будет предпринята попытка добавить повторяющийся именованный объект в дерево объектов main, новый объект будет содержать собственную автономную область имен XAML. Условие повторяющегося имени может быть обнаружено только в тот момент, когда вы подключаете объект к более крупному дереву объектов. Или исключение может возникнуть в операции, которая подключила объекты в дереве, например при вызове метода Add коллекции, которая подключается к дереву объектов main.

Может быть трудно определить, какие значения Name уже существуют в области имен XAML, в которую вы позже добавите новый объект. Нет конкретного API, который бы сообщал полную хэш-строку существующих имен в области имен XAML. Если значения Name задаются в коде широко, может потребоваться метод создания строк имен, которые являются уникальными для использования времени выполнения, или может потребоваться перенос вызовов, добавляющих новые именованные объекты в блок try-catch, чтобы перехватывать исключения, которые могут возникнуть из-за повторяющегося имени. Вы также можете добавить собственный код в реализацию InitializeComponent , которая считывает значения имен, созданные xaml.

Обратите внимание, что во время выполнения можно задать имя только для объектов FrameworkElement или Inline. Если объект не имеет свойства Name и задание имени в XAML потребовалось бы использовать атрибут x:Name , а не Name, api времени выполнения для задания имени среды выполнения такого объекта недоступен.

Применяется к