Директива x:Name

Статья
12/18/2024

Уникально идентифицирует элементы, определенные XAML, в области имен XAML. Области имен XAML и их уникальные модели можно применять к экземплярам объектов, когда платформы предоставляют API или реализуют поведение, которое обращается к графу объектов XAML во время выполнения.

Использование атрибута XAML

<object x:Name="XAMLNameValue".../>

Значения XAML

Ценность	Описание
`XAMLNameValue`	Строка, соответствующая ограничениям грамматики XamlName.

Замечания

После применения x:Name к резервной модели программирования платформы имя эквивалентно переменной, содержащей ссылку на объект или экземпляр, возвращаемый конструктором.

Значение использования директивы x:Name должно быть уникальным в области имен XAML. По умолчанию при использовании API служб XAML .NET основной области имен XAML определяется в корневом элементе XAML одной рабочей среды XAML и включает элементы, содержащиеся в этой рабочей среде XAML. Дополнительные дискретные области имен XAML, которые могут возникнуть в одной рабочей среде XAML, можно определить платформами для решения конкретных сценариев. Например, в WPF новые области имен XAML определяются и создаются любым шаблоном, который также определен в рабочей среде XAML. Дополнительные сведения о области имен XAML (написанная для WPF, но соответствующая многим понятиям области имен XAML), см. в области имен WPF XAML.

Как правило, x:Name не следует применять в ситуациях, которые также используют x:Key. Реализации XAML в конкретных существующих платформах ввели концепции подстановки между x:Key и x:Name, но это не рекомендуется. Службы XAML .NET не поддерживают такие понятия подстановки при обработке сведений об имени или ключе, таких как INameScope или DictionaryKeyPropertyAttribute.

Правила разрешения x:Name, а также принудительное применение уникальности имен потенциально определяются определенными платформами реализации. Тем не менее, чтобы использовать службы XAML .NET, определения платформы уникальности области имен XAML должны быть согласованы с определением INameScope информации в этой документации и должны использовать те же правила, касающиеся того, где применяется информация. Например, реализация Windows Presentation Foundation (WPF) разделяет различные элементы разметки на отдельные диапазоны NameScope, такие как словари ресурсов, логическое дерево, созданное XAML на уровне страницы, шаблоны и другое отложенное содержимое, а затем применяет уникальность имен XAML в каждой из этих областей имен XAML.

Для пользовательских типов, использующих средства записи объектов XAML служб .NET XAML, свойство, которое сопоставляется с x:Name типа, можно установить или изменить. Это поведение определяется путем ссылки на имя свойства для сопоставления с RuntimeNamePropertyAttribute в коде определения типа. RuntimeNamePropertyAttribute — это атрибут уровня типа.

Using.NET службах XAML поддержка резервной логики для области имен XAML может быть определена нейтральным образом, реализуя интерфейс INameScope.

Заметки об использовании WPF

В стандартной конфигурации сборки для приложения WPF, использующего XAML, частичные классы и код позади, указанный x:Name становится именем поля, созданного в базовом коде при обработке XAML задачей сборки компиляции разметки, и это поле содержит ссылку на объект. По умолчанию созданное поле является внутренним. Вы можете изменить доступ к полю, указав атрибут x:FieldModifier. В WPF и Silverlight последовательность заключается в том, что компиляция разметки определяет и именует поле в частичном классе, но значение изначально пусто. Затем созданный метод с именем InitializeComponent вызывается из конструктора классов. InitializeComponent состоит из вызовов FindName с помощью каждого из значений x:Name, которые существуют в определенной XAML части частичного класса в качестве входных строк. Затем возвращаемые значения назначаются ссылке на подобное поле для заполнения значений полей объектами, созданными из синтаксического анализа XAML. Выполнение InitializeComponent позволяет ссылаться на граф объектов времени выполнения с помощью непосредственного имени x:Name / поля, а не вызывать FindName явно в любой момент, когда требуется ссылка на определенный XAML-объект.

Для приложения WPF, использующего целевые объекты Microsoft Visual Basic и содержащий XAML-файлы с действием сборки Page, во время компиляции создается отдельное эталонное свойство, которое добавляет ключевое слово WithEvents ко всем элементам, имеющим x:Name, для поддержки синтаксиса Handles синтаксиса для делегатов обработчика событий. Это свойство всегда является общедоступным. Дополнительные сведения см. в обработки событий Visual Basic и WPF.

x:Name используется обработчиком XAML WPF для регистрации имени в области имен XAML во время загрузки, даже если страница не компилируется действиями сборки (например, свободный XAML словаря ресурсов). Одна из причин этого поведения заключается в том, что x:Name потенциально требуется для привязки ElementName. Дополнительные сведения см. в обзоре привязки данных.

Как упоминалось ранее, x:Name (или Name) не следует применять в ситуациях, которые также используют x:Key. ResourceDictionary WPF имеет особое поведение определения себя как области имен XAML, но возвращая не реализованные или null значения для INameScope API в качестве способа применения этого поведения. Если средство синтаксического анализа XAML WPF сталкивается с Name или x:Name в определяемом XAML ResourceDictionary, имя не добавляется в область имен XAML. Попытка найти это имя из любой области имен XAML и методы FindName не возвращают допустимые результаты.

x:Name и Name

Многие сценарии приложений WPF могут избежать использования атрибута x:Name, так как свойство зависимостей Name, указанное в пространстве имен XAML по умолчанию для нескольких важных базовых классов, таких как FrameworkElement и FrameworkContentElement удовлетворяет этой же цели. Существуют некоторые распространенные сценарии XAML и WPF, в которых доступ кода к элементу без Name свойств на уровне платформы важен. Например, некоторые классы поддержки анимации и раскадровки не поддерживают свойство Name, но они часто должны ссылаться в коде для управления анимацией. Вы должны указать x:Name в качестве атрибута на временных шкалах и преобразованиях, созданных в XAML, если вы планируете ссылаться на них из кода позже.

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

Name можно задать с помощью синтаксиса атрибута XAML и в коде с помощью SetValue; Обратите внимание, что установка свойства Name в коде не создает ссылку на репрезентативное поле в области имен XAML в большинстве случаев, когда XAML уже загружен. Вместо попытки задать Name в коде используйте методы NameScope из кода в соответствующем области имен.

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

Заметки об использовании Silverlight

x:Name для Silverlight документируется отдельно. Дополнительные сведения см. впространства имен XAML (x:).

Поделиться через