x:Name (Directiva)x:Name Directive

Identifica de forma única los elementos definidos por XAML en un ámbito de nombres XAML.Uniquely identifies XAML-defined elements in a XAML namescope. Los ámbitos de nombres XAML y sus modelos de unicidad se pueden aplicar a los objetos con instancias, cuando los marcos de trabajo proporcionan API o implementan comportamientos que tienen acceso al gráfico de objetos creado por XAML en tiempo de ejecución.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.

Uso de atributos XAMLXAML Attribute Usage

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

Valores XAMLXAML Values

XAMLNameValue Cadena que se ajusta a las restricciones de La gramática XamlName.A string that conforms to the restrictions of the XamlName Grammar.

ObservacionesRemarks

Después x:Name se aplica al modelo de programación de respaldo de un marco de trabajo, el nombre es equivalente a la variable que contiene una referencia de objeto o una instancia devuelta por un constructor.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.

El valor x:Name de un uso de directiva debe ser único dentro de un ámbito de nombres XAML.The value of an x:Name directive usage must be unique within a XAML namescope. De forma predeterminada, cuando se usa la API de servicios XAML de .NET, el ámbito de nombres XAML principal se define en el elemento raíz XAML de una única producción XAML y abarca los elementos contenidos en esa producción 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. Los marcos de trabajo pueden definir ámbitos de nombres XAML discretos adicionales que pueden producirse dentro de una única producción XAML para abordar escenarios específicos.Additional discrete XAML namescopes that might occur within a single XAML production can be defined by frameworks to address specific scenarios. Por ejemplo, en WPFWPF, los nuevos ámbitos de nombres XAML se definen y crean mediante cualquier plantilla que también se define en esa producción XAML.For example, in WPF, new XAML namescopes are defined and created by any template that is also defined on that XAML production. Para obtener más información acerca de los ámbitos de nombres XAML (escritos para WPF pero relevantes para muchos conceptos de ámbito de nombres XAML), vea Ámbitosde nombres XAML de WPF .For more information about XAML namescopes (written for WPF but relevant for many XAML namescope concepts), see WPF XAML Namescopes.

En general, x:Name no debe aplicarse x:Keyen situaciones que también utilizan .In general, x:Name should not be applied in situations that also use x:Key. Las implementaciones XAML de marcos existentes específicos han introducido conceptos de sustitución entre x:Key y x:Name, pero no es una práctica recomendada.XAML implementations by specific existing frameworks have introduced substitution concepts between x:Key and x:Name, but that is not a recommended practice. Los servicios XAML de .NET no admiten estos INameScope conceptos de sustitución al controlar información de nombre/clave como o DictionaryKeyPropertyAttribute..NET XAML Services does not support such substitution concepts when handling name/key information such as INameScope or DictionaryKeyPropertyAttribute.

Las normas para x:Name la permisividad, así como la aplicación de la exclusividad de los nombres, están definidas potencialmente por marcos de aplicación específicos.Rules for permittance of x:Name as well as the name uniqueness enforcement are potentially defined by specific implementing frameworks. Sin embargo, para poder usarse con los servicios XAML de .NET, las INameScope definiciones de marco de trabajo de unicidad del ámbito de nombres XAML deben ser coherentes con la definición de información de esta documentación y deben usar las mismas reglas con respecto a dónde se aplica la información.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. Por ejemplo, Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) la implementación divide NameScope varios elementos de marcado en intervalos independientes, como diccionarios de recursos, el árbol lógico creado por el XAML de nivel de página, plantillas y otro contenido diferido y, a continuación, aplica la unicidad de nombres XAML dentro de cada uno de esos ámbitos de nombres 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.

Para los tipos personalizados que usan escritores de objetos XAML de servicios XAML de .NET, se puede establecer o cambiar una propiedad que se asigna a x:Name un tipo.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. Este comportamiento se define haciendo referencia al nombre RuntimeNamePropertyAttribute de la propiedad que se asignará con el código de definición de tipo.You define this behavior by referencing the name of the property to map with the RuntimeNamePropertyAttribute in the type definition code. RuntimeNamePropertyAttributees un atributo de nivel de tipo.RuntimeNamePropertyAttribute is a type-level attribute.

Using.NET servicios XAML, la lógica de respaldo para la compatibilidad con el INameScope ámbito de nombres XAML se puede definir de forma neutral para el marco de trabajo mediante la implementación de la interfaz.Using.NET XAML Services, the backing logic for XAML namescope support can be defined in a framework-neutral way by implementing the INameScope interface.

Notas de uso de WPFWPF Usage Notes

En la configuración de WPFWPF compilación estándar para una aplicación que usa XAML, clases parciales y código subyacente, el especificado x:Name se convierte en el nombre de un campo que se crea en el código subyacente cuando XAMLXAML se procesa mediante una tarea de compilación de compilación de marcado y ese campo contiene una referencia al objeto.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. De forma predeterminada, el campo creado es interno.By default, the created field is internal. Puede cambiar el acceso a campos especificando el atributo x:FieldModifier.You can change field access by specifying the x:FieldModifier attribute. En WPFWPF y Silverlight, la secuencia es que la compilación de marcado define y nombra el campo en una clase parcial, pero el valor está inicialmente vacío.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. A continuación, se InitializeComponent llama a un método generado denominado desde dentro del constructor de clase.Then, a generated method named InitializeComponent is called from within the class constructor. InitializeComponentconsiste FindName en llamadas x:Name que usan cada uno de los valores que existen en la parte definida por XAML de la clase parcial como cadenas de entrada.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. A continuación, los valores devueltos se asignan a la referencia de campo con nombre similar para rellenar los valores de campo con objetos creados a partir del análisis 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. La ejecución InitializeComponent de hacer posible hacer referencia al x:Name gráfico de objetos de FindName tiempo de ejecución mediante el nombre de campo / directamente, en lugar de tener que llamar explícitamente cada vez que necesite una referencia a un objeto definido por 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.

Para una aplicación WPFWPF que usa los destinos Page de Microsoft Visual Basic e incluye archivos WithEvents XAML con acción de x:Namecompilación, Handles se crea una propiedad de referencia independiente durante la compilación que agrega la palabra clave a todos los elementos que tienen una sintaxis , para admitir la sintaxis para los delegados del controlador de eventos.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. Esta propiedad es siempre pública.This property is always public. Para más información, vea Control de eventos en Visual Basic y WPF.For more information, see Visual Basic and WPF Event Handling.

x:NameEl procesador XAML de WPF usa para registrar un nombre en un ámbito de nombres XAML en tiempo de carga, incluso en los casos en los que la página no está compilada por acciones de compilación con marcado (por ejemplo, XAML flexible de un diccionario de recursos).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). Una razón para este x:Name comportamiento es porque ElementName es potencialmente necesario para el enlace.One reason for this behavior is because the x:Name is potentially needed for ElementName binding. Para obtener más información, vea Información general sobre el enlacede datos .For details, see Data Binding Overview.

Como se x:Name mencionó Nameanteriormente, (o ) x:Keyno debe aplicarse en situaciones que también utilizan .As mentioned previously, x:Name (or Name) should not be applied in situations that also use x:Key. Tiene WPFWPF ResourceDictionary un comportamiento especial de definirse como un ámbito de nombres XAML INameScope pero devolver valores no implementados o valores nulos para las API como una forma de aplicar este comportamiento.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. Si el analizador XAML Name de x:Name WPF encuentra ResourceDictionaryo en un XAML definido , el nombre no se agrega a ningún ámbito de nombres 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. Al intentar encontrar ese nombre desde cualquier FindName ámbito de nombres XAML y los métodos no se devolverán resultados válidos.Attempting to find that name from any XAML namescope and the FindName methods will not return valid results.

x:Nombre y nombrex:Name and Name

Muchos escenarios de aplicación WPFWPF x:Name pueden evitar Name cualquier uso del atributo, porque la propiedad de dependencia FrameworkElement FrameworkContentElement especificada en el espacio de nombres XAML predeterminado para varias de las clases base importantes, como y satisface este mismo propósito.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. Todavía hay algunos escenarios comunes de XAML y WPF Name donde el acceso de código a un elemento sin propiedad en el nivel de marco de trabajo es importante.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. Por ejemplo, ciertas clases de Name compatibilidad con animaciones y guiones gráficos no admiten una propiedad, pero a menudo es necesario hacer referencia a ellas en el código para controlar la animación.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. Debe especificar x:Name como un atributo en las escalas de tiempo y las transformaciones que se crean en XAML, si tiene la intención de hacer referencia a ellos desde el código más adelante.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.

Si Name está disponible como una Name propiedad x:Name en la clase y se puede usar indistintamente como atributos, pero se producirá una excepción de análisis si ambos se especifican en el mismo elemento.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. Si el XAML se compila el marcado, la excepción se producirá en la compilación de marcado, de lo contrario se produce en la carga.If the XAML is markup compiled, the exception will occur on the markup compile, otherwise it occurs on load.

Namese puede establecer mediante la sintaxis SetValuede atributo XAML y en el código mediante ; Tenga en cuenta, sin embargo, que establecer la Name propiedad en el código no crea la referencia de campo representativo dentro del ámbito de nombres XAML en la mayoría de las circunstancias donde el XAML ya está cargado.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. En lugar de Name intentar establecer NameScope en el código, utilice métodos de código, con el ámbito de nombres adecuado.Instead of attempting to set Name in code, use NameScope methods from code, against the appropriate namescope.

NameTambién se puede establecer mediante la sintaxis de elemento de propiedad con texto interno, pero eso es poco común.Name can also be set using property element syntax with inner text, but that is uncommon. Por el x:Name contrario, no se puede establecer en SetValuela sintaxis del elemento de propiedad XAML o en el código mediante ; solo se puede establecer mediante la sintaxis de atributo en los objetos porque es una directiva.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.

Notas de uso de SilverlightSilverlight Usage Notes

x:Namepara Silverlight se documenta por separado.x:Name for Silverlight is documented separately. Para obtener más información, vea Espacio de nombres XAML (x:) Características del idioma (Silverlight).For more information, see XAML Namespace (x:) Language Features (Silverlight).

Consulte tambiénSee also