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

Уникально идентифицирует элементы, определенные в XAML, в области имен XAML.Uniquely identifies XAML-defined elements in a XAML namescope. Области имен XAML и их модели уникальности можно применять к экземплярам объектов, когда платформы предоставляют интерфейсы API или реализуют поведение, которое обращается к графу объектов, созданному XAML, во время выполнения.XAML namescopes and their uniqueness models can be applied to the instantiated objects, when frameworks provide APIs or implement behaviors that access the XAML-created object graph at run time.

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

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

Значения XAMLXAML Values

XAMLNameValue Строка, которая соответствует ограничениям грамматики имяxaml.A string that conforms to the restrictions of the XamlName Grammar.

КомментарииRemarks

После x:Name применения к модели программирования резервного копирования платформы имя эквивалентно переменной, содержащей ссылку на объект или экземпляр, возвращаемый конструктором.After x:Name is applied to a framework's backing programming model, the name is equivalent to the variable that holds an object reference or an instance as returned by a constructor.

Значение x:Name использования директивы должно быть уникальным в пределах области имен XAML.The value of an x:Name directive usage must be unique within a XAML namescope. По умолчанию при использовании API-интерфейсом служб XAML .NET основная область имен XAML определяется в корневом элементе XAML в одном производстве XAML и охватывает элементы, содержащиеся в этом производстве XAML.By default when used by .NET XAML Services API, the primary XAML namescope is defined at the XAML root element of a single XAML production, and encompasses the elements that are contained in that XAML production. Дополнительные дискретные области имен XAML, которые могут встречаться в одном производстве XAML, могут быть определены платформами для решения конкретных задач.Additional discrete XAML namescopes that might occur within a single XAML production can be defined by frameworks to address specific scenarios. Например, в WPF новые области имен XAML определяются и создаются любым шаблоном, который также определен в этом производстве XAML.For example, in WPF, new XAML namescopes are defined and created by any template that is also defined on that XAML production. Дополнительные сведения об областях имен XAML (написанных для WPF, но релевантных для многих основных понятий области имен XAML) см. в разделе области имен XAML WPF.For more information about XAML namescopes (written for WPF but relevant for many XAML namescope concepts), see WPF XAML Namescopes.

В общем случае x:Name не следует применять в ситуациях, которые также используют x:Key .In general, x:Name should not be applied in situations that also use x:Key. Реализации XAML по конкретным существующим платформам предоставили основные понятия подстановки между x:Key и x:Name , но это не рекомендуемый подход.XAML implementations by specific existing frameworks have introduced substitution concepts between x:Key and x:Name, but that is not a recommended practice. Службы XAML .NET не поддерживают такие основные понятия подстановки при обработке сведений о имени или ключе, таких как INameScope или DictionaryKeyPropertyAttribute ..NET XAML Services does not support such substitution concepts when handling name/key information such as INameScope or DictionaryKeyPropertyAttribute.

Правила для разрешения, а x:Name также принудительное использование уникальности имен потенциально определяются конкретными реализующими платформами.Rules for permittance of x:Name as well as the name uniqueness enforcement are potentially defined by specific implementing frameworks. Однако для использования со службами XAML .NET Framework определения уникальности области имен XAML должны быть совместимы с определением INameScope информации в этой документации и использовать те же правила, что и при применении данных.However, to be usable with .NET XAML Services, the framework definitions of XAML namescope uniqueness should be consistent with the definition of INameScope information in this documentation, and should use the same rules regarding where the information is applied. Например, Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) Реализация делит различные элементы разметки на отдельные NameScope диапазоны, такие как словари ресурсов, логическое дерево, созданное XAML на уровне страницы, шаблоны и другое отложенное содержимое, а затем обеспечивает уникальность имени XAML в каждой из этих областей имен XAML.For example, the Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) implementation divides various markup elements into separate NameScope ranges, such as resource dictionaries, the logical tree created by the page-level XAML, templates, and other deferred content, and then enforces XAML name uniqueness within each of those XAML namescopes.

Для пользовательских типов, использующих средства записи объектов XAML служб XAML .NET, свойство, сопоставляемое с x:Name типом, может быть установлено или изменено.For custom types that use .NET XAML Services XAML object writers, a property that maps to x:Name on a type can be established or changed. Это поведение определяется путем ссылки на имя свойства, сопоставляемое с объектом RuntimeNamePropertyAttribute в коде определения типа.You define this behavior by referencing the name of the property to map with the RuntimeNamePropertyAttribute in the type definition code. RuntimeNamePropertyAttribute — Это атрибут уровня типа.RuntimeNamePropertyAttribute is a type-level attribute.

Службы XAML Using.NET. логика резервного копирования для поддержки области имен XAML может быть определена независимым от платформы способом путем реализации INameScope интерфейса.Using.NET XAML Services, the backing logic for XAML namescope support can be defined in a framework-neutral way by implementing the INameScope interface.

Примечания об использовании WPFWPF Usage Notes

В стандартной конфигурации сборки для приложения, WPFWPF использующего XAML, разделяемые классы и код программной части, указанное значение x:Name становится именем поля, которое создается в базовом коде, когда XAMLXAML обрабатывается задачей построения компиляции разметки, а это поле содержит ссылку на объект.Under the standard build configuration for a WPFWPF application that uses XAML, partial classes, and code-behind, the specified x:Name becomes the name of a field that is created in the underlying code when XAMLXAML is processed by a markup compilation build task, and that field holds a reference to the object. По умолчанию созданное поле является внутренним.By default, the created field is internal. Доступ к полю можно изменить, указав атрибут КС:фиелдмодифиер.You can change field access by specifying the x:FieldModifier attribute. В WPF и Silverlight последовательность состоит в том, что компиляция разметки определяет и называет поле в разделяемом классе, но значение изначально пустое.In WPF and Silverlight, the sequence is that the markup compile defines and names the field in a partial class, but the value is initially empty. Затем в InitializeComponent конструкторе класса вызывается созданный метод с именем.Then, a generated method named InitializeComponent is called from within the class constructor. InitializeComponent состоит из FindName вызовов, использующих каждое из x:Name значений, которые существуют в определяемой XAML части разделяемого класса в качестве входных строк.InitializeComponent consists of FindName calls using each of the x:Name values that exist in the XAML-defined part of the partial class as input strings. Затем возвращаемые значения присваиваются ссылке на поле Like-Name, чтобы заполнить значения полей объектами, созданными из синтаксического анализа XAML.The return values are then assigned to the like-named field reference to fill the field values with objects that were created from XAML parsing. Выполнение InitializeComponent позволяет ссылаться на граф объектов времени выполнения x:Name напрямую, используя имя поля/, а не вызывать FindName явно каждый раз, когда требуется ссылка на объект, определенный XAML.The execution of InitializeComponent make it possible to reference the run time object graph using the x:Name / field name directly, rather than having to call FindName explicitly any time you need a reference to a XAML-defined object.

Для приложения WPF, которое использует Visual Basic Майкрософт и включает XAML-файлы с Page действием сборки, во время компиляции создается отдельное свойство ссылки, которое добавляет WithEvents ключевое слово ко всем элементам, имеющим x:Name , для поддержки Handles синтаксиса для делегатов обработчиков событий.For a WPF application that uses the Microsoft Visual Basic targets and includes XAML files with Page build action, a separate reference property is created during compilation that adds the WithEvents keyword to all elements that have an x:Name, to support Handles syntax for event handler delegates. Это свойство всегда является открытым.This property is always public. Дополнительные сведения см. в разделе Обработка событий в Visual Basic и WPF.For more information, see Visual Basic and WPF Event Handling.

x:Name используется обработчиком XAML WPF для регистрации имени в области имен XAML во время загрузки, даже если страница не скомпилирована разметкой с помощью действий сборки (например, свободный XAML словаря ресурсов).x:Name is used by the WPF XAML processor to register a name into a XAML namescope at load time, even for cases where the page is not markup-compiled by build actions (for example, loose XAML of a resource dictionary). Одна из причин такого поведения заключается в том, что может x:Name потребоваться для ElementName привязки.One reason for this behavior is because the x:Name is potentially needed for ElementName binding. Дополнительные сведения см. в разделе Общие сведения о привязке данных.For details, see Data Binding Overview.

Как упоминалось ранее, x:Name (или Name ) не следует применять в ситуациях, которые также используют x:Key .As mentioned previously, x:Name (or Name) should not be applied in situations that also use x:Key. Объект WPFWPF ResourceDictionary имеет специальное поведение, определяющее себя как область имен XAML, но возвращающая не реализованные или значения NULL для INameScope интерфейсов API в качестве способа обеспечения этого поведения.The WPFWPF ResourceDictionary has a special behavior of defining itself as a XAML namescope but returning Not Implemented or null values for INameScope APIs as a way to enforce this behavior. Если средство синтаксического анализа XAML WPF обнаруживает Name или x:Name находится в определенном XAML ResourceDictionary , оно не добавляется в область имен XAML.If the WPF XAML parser encounters Name or x:Name in a XAML-defined ResourceDictionary, the name is not added to any XAML namescope. Попытка найти это имя из любой области имен XAML и FindName методы не будут возвращать допустимые результаты.Attempting to find that name from any XAML namescope and the FindName methods will not return valid results.

x:Name и Namex:Name and Name

Многие сценарии приложений WPF могут избегать использования x:Name атрибута, поскольку Name свойство зависимостей указано в пространстве имен XAML по умолчанию для нескольких важных базовых классов, таких как FrameworkElement , и FrameworkContentElement соответствует этой цели.Many WPF application scenarios can avoid any use of the x:Name attribute, because the Name dependency property as specified in the default XAML namespace for several of the important base classes such as FrameworkElement and FrameworkContentElement satisfies this same purpose. По-прежнему существуют некоторые распространенные сценарии XAML и WPF, в которых важна возможность доступа кода к элементу, не имеющему Name свойств на уровне платформы.There are still some common XAML and WPF scenarios where code access to an element with no Name property at the framework level is important. Например, некоторые классы поддержки анимации и раскадровки не поддерживают Name свойство, но для управления анимацией часто требуется ссылка в коде.For example, certain animation and storyboard support classes do not support a Name property, but they often need to be referenced in code in order to control the animation. Необходимо указать в x:Name качестве атрибута для временных шкал и преобразований, созданных в XAML, если вы собираетесь ссылаться на них из кода позже.You should specify x:Name as an attribute on timelines and transforms that are created in XAML, if you intend to reference them from code later.

Значение, если Name свойство доступно в качестве свойства класса Name и x:Name может использоваться как атрибуты, но если оба указаны в одном элементе, будет получено исключение Parse.If Name is available as a property on the class, Name and x:Name can be used interchangeably as attributes, but a parse exception will result if both are specified on the same element. Если XAML разкомпилируется в разметке, исключение будет происходить при компиляции разметки, в противном случае это произойдет при загрузке.If the XAML is markup compiled, the exception will occur on the markup compile, otherwise it occurs on load.

Name можно задать с помощью синтаксиса атрибутов XAML и в коде, использующем SetValue . Обратите внимание, что установка Name свойства в коде не приводит к созданию ссылки на репрезентативное поле в области имен XAML в большинстве случаев, когда XAML уже загружен.Name can be set using XAML attribute syntax, and in code using SetValue; note however that setting the Name property in code does not create the representative field reference within the XAML namescope in most circumstances where the XAML is already loaded. Вместо того чтобы пытаться задать Name в коде, используйте NameScope методы из кода для соответствующей области имен.Instead of attempting to set Name in code, use NameScope methods from code, against the appropriate namescope.

Name также можно задать с помощью синтаксиса элемента свойства с внутренним текстом, но это не так часто.Name can also be set using property element syntax with inner text, but that is uncommon. Напротив, x:Name не может быть задано в синтаксисе элемента свойства XAML или в коде с помощью SetValue ; его можно задать только с помощью синтаксиса атрибутов для объектов, так как это директива.In contrast, x:Name cannot be set in XAML property element syntax, or in code using SetValue; it can only be set using attribute syntax on objects because it is a directive.

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

x:Name для Silverlight задокументировано отдельно.x:Name for Silverlight is documented separately. Дополнительные сведения см. в разделе пространство имен XAML (x:). Функции языка (Silverlight).For more information, see XAML Namespace (x:) Language Features (Silverlight).

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