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 ejecución 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.

ComentariosRemarks

Una vez que se aplica x:Name 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 de 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 uso de la Directiva x:Name 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 lo usa .NET Framework API de servicios XAML, el ámbito de nombres XAML primario se define en el elemento raíz XAML de una sola producción XAML y engloba los elementos contenidos en esa producción 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. Los marcos de trabajo de XAML discretos adicionales que pueden producirse en 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, los ámbitos de nuevo XAML se definen y crean en cualquier 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 sobre los ámbitos de nombres XAML (escritos para WPF pero relevantes para muchos conceptos de ámbito de nombres XAML), vea ámbitos de 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 se deben aplicar en situaciones que también usan x:Key.In general, x:Name should not be applied in situations that also use x:Key. Las implementaciones de XAML de los marcos de trabajo 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. .NET Framework los servicios XAML no admiten estos conceptos de sustitución al tratar la información de nombre o clave, como 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 la concesión de x:Name, así como la aplicación de la unicidad del nombre, pueden definirse mediante marcos de implementació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 que se pueda usar con .NET Framework servicios XAML, las definiciones de Framework de la singularidad del ámbito de nombres XAML deben ser coherentes con la definición de INameScope información de esta documentación y deben utilizar las mismas reglas en cuanto a 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, la implementación de Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) divide varios elementos de marcado en intervalos de NameScope independientes, como diccionarios de recursos, el árbol lógico creado por el XAML de nivel de página, plantillas y otro contenido aplazado y, a continuación, aplica el nombre XAML. unicidad dentro de cada uno de esos ámbitos de código 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.

En el caso de los tipos personalizados que utilizan .NET Framework los escritores de objetos XAML de los servicios XAML, se puede establecer o cambiar una propiedad que se asigna a x:Name en un tipo.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. Este comportamiento se define haciendo referencia al nombre de la propiedad que se va a asignar al RuntimeNamePropertyAttribute en 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. RuntimeNamePropertyAttribute es un atributo de nivel de tipo.RuntimeNamePropertyAttribute is a type-level attribute.

Los servicios XAML de Using.NET Framework, la lógica de respaldo para la compatibilidad con el ámbito de nombres XAML se puede definir en un modo independiente del marco implementando la interfaz INameScope.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 de WPFWPF Usage Notes

En la configuración de compilación estándar para una aplicación WPFWPF que usa XAML, clases parciales y código subyacente, el x:Name especificado se convierte en el nombre de un campo que se crea en el código subyacente cuando una compilación de compilación de marcado procesa XAMLXAML Task 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 atributo x:FieldModifier (.You can change field access by specifying the x:FieldModifier attribute. En WPF 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 llama a un método generado denominado InitializeComponent desde dentro del constructor de clase.Then, a generated method named InitializeComponent is called from within the class constructor. InitializeComponent consta de FindName llamadas mediante cada uno de los valores de x:Name 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. Los valores devueltos 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 del análisis de 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 de InitializeComponent permite hacer referencia al gráfico de objetos en tiempo de ejecución mediante el nombre de x:Name/campo directamente, en lugar de tener que llamar a FindName explícitamente cada vez que se necesita 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 de WPF que usa los destinos de Microsoft Visual Basic e incluye archivos XAML con Page acción de compilación, se crea una propiedad de referencia independiente durante la compilación que agrega la palabra clave WithEvents a todos los elementos que tienen un x:Name, para admitir @no Sintaxis de _t_3 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.

el procesador XAML de WPF usa x:Name 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 (por ejemplo, XAML dinámico 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). Uno de los motivos de este comportamiento se debe a que la x:Name es necesaria para el enlace de ElementName.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 enlace de datos.For details, see Data Binding Overview.

Como se mencionó anteriormente, x:Name (o Name) no se deben aplicar en situaciones en las que también se use x:Key.As mentioned previously, x:Name (or Name) should not be applied in situations that also use x:Key. El ResourceDictionary de WPFWPF tiene un comportamiento especial para definirse como un ámbito de nombres XAML, pero para devolver los valores no implementados o null para las API de INameScope 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 XAML de WPF encuentra Name o x:Name en un ResourceDictionarydefinido por XAML, 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. Si se intenta encontrar ese nombre desde cualquier ámbito de nombres XAML y los métodos de FindName, 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:Name y Namex:Name and Name

Muchos escenarios de aplicaciones de WPF pueden evitar el uso del atributo x:Name, porque la propiedad de dependencia Name como se especifica en el espacio de nombres XAML predeterminado para varias de las clases base 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 en los que el acceso al código a un elemento sin 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, algunas clases de compatibilidad con animaciones y guiones gráficos no admiten una propiedad Name, 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 atributo en las escalas de tiempo y las transformaciones que se crean en XAML, si tiene previsto 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 propiedad en la clase, Name y x:Name se pueden 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 se compila el marcado XAML, la excepción se producirá en la compilación de marcado; en caso contrario, se producirá en la carga.If the XAML is markup compiled, the exception will occur on the markup compile, otherwise it occurs on load.

Name se pueden establecer mediante la sintaxis de atributo XAML y en el código mediante SetValue; sin embargo, tenga en cuenta que al establecer la propiedad Name en el código no se crea la referencia de campo representativa dentro del ámbito de nombres XAML en la mayoría de los casos en los que 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 intentar establecer Name en el código, use NameScope métodos del 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.

también se puede establecer Name mediante la sintaxis de elementos de propiedad con texto interno, pero esto no es habitual.Name can also be set using property element syntax with inner text, but that is uncommon. En cambio, no se puede establecer x:Name en la sintaxis de elementos de propiedad XAML o en código mediante SetValue; solo se puede establecer mediante 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, vea espacio de nombres XAML (x:) Características del lenguaje (Silverlight).For more information, see XAML Namespace (x:) Language Features (Silverlight).

Vea tambiénSee also