x:Name (Directiva)

  • Artículo

Identifica de forma única los elementos definidos por XAML en un ámbito de nombres XAML. Los ámbitos de nombres XAML y sus modelos de unicidad se pueden aplicar a los objetos creados por instancias cuando los marcos proporcionan API o implementan comportamientos que acceden al gráfico de objetos creados por XAML en tiempo de ejecución.

Uso de atributos XAML

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

Valores XAML

Value Descripción
XAMLNameValue Una cadena que cumple con las restricciones de la gramática XamlName.

Comentarios

Después de aplicar x:Name al modelo de programación de respaldo de un marco, el nombre es equivalente a la variable que contiene una referencia de objeto o una instancia tal y como la devuelve un constructor.

El valor de un uso de directiva x:Name debe ser único dentro de un ámbito de nombres XAML. De forma predeterminada, cuando se usa por la API de servicios XAML de .NET, el ámbito de nombres XAML principal se define en el elemento raíz XAML de una sola producción XAML y abarca los elementos contenidos en esa producción XAML. Los ámbitos de nombres XAML discretos adicionales que pueden producirse dentro de una sola producción XAML se pueden definir mediante marcos para abordar escenarios específicos. Por ejemplo, en WPF los nuevos ámbitos de nombres XAML se definen y crean mediante cualquier plantilla que también esté definida en esa producción XAML. 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), consulte Ámbitos de nombres XAML de WPF.

En general x:Name no se debe aplicar en situaciones que también usen x:Key. Las implementaciones XAML por marcos existentes específicos han introducido conceptos de sustitución entre x:Key y x:Name, pero no es una práctica recomendada. Los servicios XAML de .NET no admiten estos conceptos de sustitución cuando controlan información de nombre o clave como INameScope o DictionaryKeyPropertyAttribute.

Las reglas para permitir x:Name, así como la aplicación de unicidad de nombres, se definen potencialmente mediante marcos de implementación específicos. Sin embargo, para poder usarse con los servicios XAML de .NET, las definiciones de marco de la unicidad del ámbito de nombres XAML deben ser coherentes con la definición de información INameScope de esta documentación y deben usar las mismas reglas con respecto a dónde se aplica la información. Por ejemplo, la implementación de Windows Presentation Foundation (WPF) divide varios elementos de marcado en intervalos independientes NameScope, 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 del nombre XAML dentro de cada uno de esos ámbitos de nombres XAML.

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 en un tipo. Para definir este comportamiento, haga referencia al nombre de la propiedad que se va a asignar con el RuntimeNamePropertyAttribute en el código de definición de tipo. RuntimeNamePropertyAttribute es un atributo de nivel de tipo.

Al usar los servicios XAML de .NET, la lógica de respaldo para la compatibilidad con el ámbito de nombres XAML se puede definir de forma neutra en el marco mediante la implementación de la interfaz INameScope.

Notas de uso de WPF

En la configuración de compilación estándar de una aplicación WPF 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 tarea de creación de compilación de marcado procesa XAML y ese campo contiene una referencia al objeto. De forma predeterminada, el campo creado es interno. Puede cambiar el acceso de campo especificando el atributo x:FieldModifier. En WPF y Silverlight, la secuencia es que la compilación de marcado define y asigna un nombre al campo en una clase parcial, pero el valor está vacío inicialmente. A continuación, se llama a un método generado denominado InitializeComponent desde dentro del constructor de clase. InitializeComponent consta de llamadas FindName que usan cada uno de los valores x:Name que existen en la parte definida por XAML de la clase parcial como cadenas de entrada. 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. La ejecución de InitializeComponent permite hacer referencia al gráfico de objetos en tiempo de ejecución mediante el /nombre del campo x:Namedirectamente, en lugar de tener que llamar explícitamente a FindName en cualquier momento en que se necesite una referencia a un objeto definido por XAML.

Para una aplicación WPF que usa los destinos de Microsoft Visual Basic e incluye archivos XAML con la acción de compilación Page, 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 la sintaxis de Handles para los delegados del controlador de eventos. Esta propiedad siempre es pública. Para más información, vea Control de eventos en Visual Basic y WPF.

x:Name lo usa el procesador XAML de WPF 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 marcado mediante acciones de compilación (por ejemplo, XAML dinámico de un diccionario de recursos). Una razón para este comportamiento es que es posible que x:Name sea necesario para el enlace de ElementName. Para obtener información, consulte Información general sobre enlace de datos.

Como se ha mencionado anteriormente, x:Name (o Name) no se debe aplicar en situaciones que también usen x:Key. El ResourceDictionary de WPF tiene un comportamiento especial de definirse a sí mismo como un ámbito de nombres XAML, pero devolviendo valores No implementado o NULL para las API de INameScope como una manera de aplicar este comportamiento. 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. Intentar buscar ese nombre desde cualquier ámbito de nombres XAML y los métodos FindName no devolverán resultados válidos.

x:Name y Name

Muchos escenarios de aplicación de WPF pueden evitar cualquier uso del atributo x:Name, ya que la propiedad Name de dependencia tal como se especifica en el espacio de nombres XAML predeterminado para varias de las clases base importantes, como FrameworkElement y FrameworkContentElement, satisface este mismo propósito. Todavía hay algunos escenarios comunes de XAML y WPF en los que el acceso del código a un elemento sin propiedad Name en el nivel de marco es importante. Por ejemplo, ciertas clases de compatibilidad con animaciones y guiones gráficos no admiten una propiedad Name, pero a menudo debe hacerse referencia a ellas en el código para controlar la animación. Si quiere hacer referencia a ellos más adelante desde el código, debería especificar x:Name como un atributo en escalas de tiempo y transformaciones que se crean en XAML.

Si Name está disponible como una propiedad en la clase, Name y x:Name se pueden usar indistintamente como atributos, pero se iniciará una excepción de análisis si ambos se especifican en el mismo elemento. Si el código XAML está compilado por marcado, la excepción se iniciará en la compilación de marcado; de lo contrario, se produce al cargarse.

Name se puede establecer mediante la sintaxis de atributo XAML y en el código, mediante SetValue. Sin embargo, tenga en cuenta que establecer la propiedad Name en el código no crea la referencia de campo representativa dentro del ámbito de nombres XAML en la mayoría de las circunstancias en las que el XAML ya está cargado. En lugar de intentar establecer Name en el código, use métodos de NameScope desde el código en el ámbito de nombres adecuado.

Name también se puede establecer mediante la sintaxis de elementos de propiedad con texto interno, pero esto es poco frecuente. Por el contrario, x:Name no se puede establecer en la sintaxis del elemento de propiedad XAML ni en el código mediante SetValue; solo se puede establecer mediante la sintaxis de atributo en objetos porque es una directiva.

Notas de uso de Silverlight

x:Name para Silverlight se documenta por separado. Para obtener más información, consulte Características de lenguaje (x:) del espacio de nombres de XAML (Silverlight).

Vea también