Compartir a través de

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 grafo de objetos creados por XAML en tiempo de ejecución.

Uso de atributos XAML

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

Valores XAML

Valor Descripción
XAMLNameValue Cadena que se ajusta a las restricciones de la gramática xamlName de .

Observaciones

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 como 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 en 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), consulta ámbitos de nombres XAML de WPF.

En general, no se deben aplicar x:Name en situaciones que también usen 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. Los servicios XAML de .NET no admiten estos conceptos de sustitución al controlar información de nombre o clave, como INameScope o DictionaryKeyPropertyAttribute.

Las reglas para la autorización de x:Name, así como la aplicación de unicidad de nombres, pueden definirse 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 INameScope información 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 de NameScope independientes, como diccionarios de recursos, el árbol lógico creado por el XAML de nivel de página, las 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.

Using.NET servicios XAML, la lógica de respaldo para la compatibilidad con el ámbito de nombres XAML se puede definir de forma neutral 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 xaml se procesa mediante una tarea de compilación de compilación de marcado 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á inicialmente vacío. A continuación, se llama a un método generado denominado InitializeComponent desde el constructor de clase. InitializeComponent consta de llamadas FindName con cada uno de los valores de 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 de campo o x:Name directamente, en lugar de tener que llamar a FindName explícitamente cada vez que necesites 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 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 Handles sintaxis para delegados del controlador de eventos. Esta propiedad siempre es pública. Para obtener más información, vea Visual Basic y control de eventos de WPF.

el procesador XAML de WPF usa x:Name para registrar un nombre en un ámbito de nombres XAML en el tiempo de carga, incluso en los casos en los que la página no está compilada por acciones de compilación (por ejemplo, XAML flexible de un diccionario de recursos). Una razón para este comportamiento es porque el x:Name es posible que se necesite para ElementName enlace. Para obtener más información, consulte Información general del enlace de datos.

Como se mencionó anteriormente, x:Name (o Name) no se deben aplicar en situaciones que también usen x:Key. El ResourceDictionary de WPF tiene un comportamiento especial de definirse como un ámbito de nombres XAML, pero devolver valores No implementados o NULL para INameScope API 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. Si intenta 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 wpF pueden evitar cualquier uso del atributo x:Name, ya que la propiedad de dependencia Name 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 de código a un elemento sin Name propiedad en el nivel de marco es importante. Por ejemplo, ciertas clases de animación y guion gráfico no admiten una propiedad Name, pero a menudo deben hacerse referencia en el código para controlar la animación. Debes especificar x:Name como atributo en escalas de tiempo y transformaciones que se crean en XAML, si quieres hacer referencia a ellos desde el código más adelante.

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

Name se puede establecer mediante la sintaxis de atributos XAML y en el código mediante SetValue; Tenga en cuenta, sin embargo, 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 las circunstancias en las que el XAML ya está cargado. En lugar de intentar establecer Name en el código, use NameScope métodos del código en el ámbito de nombres adecuado.

Name también se puede establecer mediante la sintaxis de elemento de propiedad con texto interno, pero es poco común. 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, consulta características del lenguaje XAML (x:) (Silverlight).

Consulte también