x:Name (Directiva)x:Name Directive

Identifica los elementos definidos por XAML en un ámbito de nombres XAML.Uniquely identifies XAML-defined elements in a XAML namescope. Ámbitos de nombres XAML y sus modelos de unicidad pueden aplicarse a los objetos con instancias, cuando marcos proporcionan API o implementan comportamientos que tienen acceso al gráfico de objetos creados 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 Una cadena que se ajusta a las restricciones de la gramática de XamlName.A string that conforms to the restrictions of the XamlName Grammar.

ComentariosRemarks

Después de x:Name se aplica a un marco de trabajo de respaldo del modelo de programación, 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 de un x:Name la directiva de uso debe ser única 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 mediante la API de servicios XAML de .NET Framework, el ámbito de nombres XAML primario se define en el elemento raíz XAML de una sola producción de XAML y abarca los elementos que se encuentran en ese producción de XAML.By default when used by .NET Framework 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. Más ámbitos de nombres XAML discretos que se produzcan dentro de una sola producción de XAML pueden definirse mediante marcos para abordar escenarios concretos.Additional discrete XAML namescopes that might occur within a single XAML production can be defined by frameworks to address specific scenarios. Por ejemplo, en WPF, nuevos ámbitos de nombres XAML se definen y creados por una plantilla que también se define en esa producción de 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 pertinente para muchos conceptos de ámbito de nombres XAML), consulte ámbitos de nombres de 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 se debe aplicar en situaciones que también usan x:Key.In general, x:Name should not be applied in situations that also use x:Key. Implementaciones de XAML específicas marcos existentes han introducido los conceptos de sustitución entre x:Key y x:Name, pero que 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. Servicios XAML de .NET framework no admite estos conceptos de sustitución cuando se administran como información de clave de nombre/ INameScope o DictionaryKeyPropertyAttribute..NET Framework XAML Services does not support such substitution concepts when handling name/key information such as INameScope or DictionaryKeyPropertyAttribute.

Las reglas para permitir de x:Name , así como el cumplimiento de unicidad nombre potencialmente se definen mediante 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 usarlo con los servicios XAML de .NET Framework, las definiciones de marco de trabajo de la unicidad de ámbito de nombres XAML deben ser coherentes con la definición de INameScope información en esta documentación y debe usar las mismas reglas sobre dónde el la información se aplica.However, to be usable with .NET Framework 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, el Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) implementación distintos elementos de marcado divide en diferentes NameScope intervalos, como diccionarios de recursos, el árbol lógico creado por el nivel de página XAML, plantillas y otros aplazada contenido y, a continuación, aplica XAML exclusividad del nombre dentro de cada uno de los á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 los escritores de objetos XAML de los servicios XAML de .NET Framework, una propiedad que se asigna a x:Name en tipo se puede establecer o cambiar.For custom types that use .NET Framework XAML Services XAML object writers, a property that maps to x:Name on a type can be established or changed. Definir este comportamiento mediante referencia al nombre de la propiedad para asignar el RuntimeNamePropertyAttribute en el código de la 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. RuntimeNamePropertyAttribute es un atributo de nivel de tipo.RuntimeNamePropertyAttribute is a type-level attribute.

Servicios de XAML Using.NET Framework, la lógica de respaldo para la compatibilidad de ámbito de nombres XAML se pueden definir en una manera independiente del marco de trabajo mediante la implementación de la INameScope interfaz.Using.NET Framework 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 WPFWPF Usage Notes

En la configuración de compilación estándar para un WPFWPF aplicación que utiliza XAML, clases parciales y código subyacente, especificado x:Name se convierte en el nombre de un campo que se crea en la base de código al XAMLXAML procesados por un elemento de marcado tarea de compilación de la compilación 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 al campo especificando el x: FieldModifier (atributo).You can change field access by specifying the x:FieldModifier attribute. En WPF y Silverlight, la secuencia es que define la compilación de marcado y los nombres de campo en una clase parcial, pero el valor inicialmente está 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, un método generado denominado InitializeComponent se llama desde dentro del constructor de clase.Then, a generated method named InitializeComponent is called from within the class constructor. InitializeComponent consta de FindName llama con cada uno de los x:Name valores que existen en el elemento definido por XAML de la clase parcial, como las 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. Los valores devueltos, a continuación, se asignan a la referencia del campo con el mismo nombre para rellenar los valores de campo con los objetos que se crearon a partir de XAML de análisis.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 de InitializeComponent hacer posible la referencia que el gráfico de objeto de tiempo de ejecución utilizando la x:Name / nombre de campo directamente, en lugar de tener que llamar a FindName 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 un WPF aplicación que utiliza Microsoft Visual Basic tiene como destino e incluye los archivos XAML con Page acción de compilación, una propiedad de referencia independiente se crea durante la compilación que agrega el WithEvents palabra clave a todos los elementos que tienen un x:Name, para admitir Handles sintaxis para los delegados de 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 siempre es 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:Name se usa el procesador de WPF XAML para registrar un nombre en un ámbito de nombres XAML en tiempo de carga, incluso en aquellos casos donde la página no está compilado por marcado mediante acciones de compilación (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 comportamiento es que el x:Name potencialmente es necesaria para ElementName enlace.One reason for this behavior is because the x:Name is potentially needed for ElementName binding. Para obtener más información, consulte Data Binding Overview.For details, see Data Binding Overview.

Como se mencionó anteriormente, x:Name (o Name) no se debe aplicar en situaciones que también usan x:Key.As mentioned previously, x:Name (or Name) should not be applied in situations that also use x:Key. El WPFWPF ResourceDictionary tiene un comportamiento especial de definición de sí mismo como un ámbito de nombres XAML, pero devolver no implementado o valores nulos para INameScope API como una manera 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 de WPF XAML encuentra Name o x:Name en definida en XAML ResourceDictionary, el nombre no se agrega a cualquier á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. Intentando buscar ese nombre en cualquier ámbito de nombres XAML y el FindName métodos no devolverán resultados válidos.Attempting to find that name from any XAML namescope and the FindName methods will not return valid results.

x: Name y nombrex:Name and Name

Muchos escenarios de aplicación de WPF pueden evitar cualquier uso de la x:Name atributo, porque el Name propiedad de dependencia como especificadas en el valor predeterminado el espacio de nombres XAML para varias de las clases bases importantes como FrameworkElement y FrameworkContentElement cumple 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 acceso a un elemento sin ningún código donde Name propiedad en el nivel de marco 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, no admiten ciertas clases de soporte técnico de animación y guiones gráficos una Name propiedad, pero a menudo es necesario hacer referencia en el código con el fin de 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. Se debe especificar x:Name como un atributo en escalas de tiempo y transformaciones que se crean en XAML, si va a 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 propiedad en la clase, Name y x:Name pueden usarse indistintamente como atributos, pero se producirá una excepción de análisis si se especifican ambos 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 es compilado por marcado, se producirá la excepción en la compilación de marcado, en caso 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.

Name se puede establecer mediante sintaxis de atributo XAML y en el código mediante SetValue; sin embargo, observe esa configuración la Name propiedad en el código no crea la referencia del campo representativo dentro del ámbito de nombres XAML en la mayoría de los casos donde el XAML ya está puede cargar.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 intentar establecer Name en código, utilice NameScope métodos desde el código, en el ámbito de nombres adecuado.Instead of attempting to set Name in code, use NameScope methods from code, against the appropriate namescope.

Name También se puede establecer utilizando la sintaxis de elemento de propiedad con el texto interno, pero que es poco habitual.Name can also be set using property element syntax with inner text, but that is uncommon. En cambio, x:Name no se puede establecer en la sintaxis de elemento de propiedad XAML o en el código mediante SetValue; solo se puede establecer utilizando la sintaxis de atributo en 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:Name para Silverlight se documenta por separado.x:Name for Silverlight is documented separately. Para obtener más información, consulte XAML Namespace (x:) Características del lenguaje (Silverlight).For more information, see XAML Namespace (x:) Language Features (Silverlight).

Vea tambiénSee also