FrameworkElement.Name Свойство

  • Ссылка

Определение

Пространство имен:
Microsoft.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();
}

Комментарии

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

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

Параметр x:Name или Name в XAML, определяющий элементы пользовательского интерфейса, поддерживает несколько основных сценариев:

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

FindName

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

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

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

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

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

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

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

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

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

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

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

См. также раздел