Compartir a través de

x:Key (Directiva)

  • Artículo

Identifica de forma única los elementos creados y a los que se hace referencia en un diccionario definido por XAML. Agregar un valor de x:Key a un elemento de objeto XAML es la manera más común de identificar un recurso en un diccionario de recursos, por ejemplo, en un wpF ResourceDictionary.

Uso de atributos XAML

<object x:Key="stringKeyValue".../>  
-or-  
<object x:Key="{markupExtensionUsage}".../>

Uso de atributos XAML (específico de WPF)

<object.Resources>  
  <object x:Key="stringKeyValue".../>  
</object.Resources>  
-or-  
<object.Resources>  
  <object x:Key="{markupExtensionUsage}".../>  
</object.Resources>

Valores XAML

Valor Descripción
stringKeyValue Cadena de texto que se va a usar como clave. La cadena de texto debe ajustarse alde gramática xamlName de .
markupExtensionUsage Dentro de los delimitadores de extensión de marcado {}, un uso de extensión de marcado que proporciona un objeto que se va a usar como clave. Vea comentarios.

Observaciones

x:Key admite el concepto de diccionario de recursos XAML. XAML como lenguaje no define una implementación de diccionario de recursos, que queda a marcos de interfaz de usuario específicos. Para obtener más información sobre cómo se implementan los diccionarios de recursos XAML en WPF, consulte Información general de recursos XAML (WPF .NET).

En XAML 2006 y WPF, se deben proporcionar x:Key como atributo . Todavía puede usar claves que no son de cadena, pero esto requiere un uso de extensión de marcado para proporcionar el valor de no cadena en formato de atributo. Si usas XAML 2009, x:Key se puede especificar como un elemento para admitir explícitamente diccionarios clavedos por tipos de objeto distintos de cadenas sin necesidad de un intermedio de extensión de marcado. Consulta la sección "XAML 2009" de este tema. El resto de la sección Comentarios se aplica específicamente a la implementación de XAML 2006.

El valor de atributo de puede ser cualquier cadena definida en el de gramática xamlName o puede ser un objeto evaluado a través de una extensión de marcado. Vea "Notas de uso de WPF" para obtener un ejemplo de WPF.

Los elementos secundarios de un elemento primario que es una implementación de IDictionary deben incluir normalmente un atributo x:Key que especifica un valor de clave único dentro de ese diccionario. Los marcos pueden implementar propiedades clave con alias para sustituir x:Key en tipos concretos; Los tipos que definen estas propiedades deben atribuirse con DictionaryKeyPropertyAttribute.

El código equivalente de especificar x:Key es la clave que se usa para el IDictionarysubyacente. Por ejemplo, un x:Key que se aplica en el marcado de un recurso en WPF equivale al valor del parámetro key de ResourceDictionary.Add al agregar el recurso a un ResourceDictionary wpF en el código.

Notas de uso de WPF

Los objetos secundarios de un objeto primario que es una implementación de IDictionary, como wpF ResourceDictionary, normalmente deben incluir un atributo x:Key y el valor de clave debe ser único dentro de ese diccionario. Hay dos excepciones importantes:

  • Algunos tipos de WPF declaran una clave implícita para el uso del diccionario. Por ejemplo, un Style con un TargetType, o un DataTemplate con un DataType, puede estar en un ResourceDictionary y usar la clave implícita.

  • WPF admite un concepto de diccionario de recursos combinado. Las claves se pueden compartir entre los diccionarios combinados y se puede acceder al comportamiento de clave compartida mediante FindResource. Para obtener más información, consulte diccionarios de recursos combinados.

En el modelo general de aplicación y implementación xaml de WPF, el compilador de marcado XAML no comprueba la unicidad de claves. En su lugar, los valores que faltan o no x:Key provocan errores del analizador XAML en tiempo de carga. Sin embargo, el control de Visual Studio de diccionarios para WPF a menudo puede tener en cuenta estos errores en la fase de diseño.

Tenga en cuenta que, en la sintaxis mostrada, el objeto ResourceDictionary es implícito en cómo el procesador XAML de WPF genera una colección para rellenar una colección Resources. Normalmente, un ResourceDictionary no se proporciona explícitamente como un elemento en el marcado, aunque puede ser en algunos casos si se desea mayor claridad (sería un elemento de objeto de colección entre el elemento de propiedad Resources y los elementos de que rellenan el diccionario). Para obtener información sobre por qué un objeto de colección es casi siempre un elemento implícito en el marcado, consulta sintaxis XAML en detalle.

En la implementación xaml de WPF, el control de las claves de diccionario de recursos se define mediante la clase abstracta ResourceKey. Sin embargo, el procesador XAML de WPF genera diferentes tipos de extensión subyacentes para las claves en función de sus usos. Por ejemplo, la clave de un DataTemplate o cualquier clase derivada se controla por separado y genera un objeto DataTemplateKey distinto.

Las claves y los nombres usan diferentes directivas y elementos de lenguaje (x:Key frente a x:Name) en la definición de XAML básica. Las claves y los nombres también se usan en diferentes situaciones por la definición de WPF y la aplicación de estos conceptos. Para obtener más información, consulta ámbitos de nombres XAML de WPF.

Como se indicó anteriormente, el valor de una clave se puede proporcionar a través de una extensión de marcado y puede ser distinto de un valor de cadena. Un escenario de WPF de ejemplo es que el valor de x:Key puede ser un ComponentResourceKey. Algunos controles exponen una clave de estilo de ese tipo para un recurso de estilo personalizado que influye en parte de la apariencia y el comportamiento de ese control sin reemplazar totalmente el estilo. Un ejemplo de este tipo de clave es ButtonStyleKey.

La característica de diccionario combinado de WPF presenta consideraciones adicionales sobre la unicidad clave y el comportamiento de búsqueda de claves. Para obtener más información, consulte diccionarios de recursos combinados.

XAML 2009

XAML 2009 relaja la restricción que x:Key siempre se proporciona en forma de atributo.

En WPF, puedes usar características xaml 2009, pero solo para XAML que no esté compilada con marcado. Xaml compilado con marcado para WPF y la forma BAML de XAML no admiten actualmente las palabras clave y características xaml 2009.

En XAML 2009, puedes especificar x:Key elementos a través del uso siguiente:

Uso de elementos XAML (solo XAML 2009)

<object>  
  <x:Key>  
keyObject  
  </x:Key>  
...  
</object>

Valores XAML

Valor Descripción
keyObject Elemento Object del objeto que se usa como clave para un object determinado en un diccionario especializado.

  • El contenedor o elemento primario para este tipo de uso no se muestra aquí. object se espera que sea un elemento secundario de un elemento de objeto que represente una implementación de diccionario especializada. keyObject se espera que sea una instancia de objeto (o un valor de un tipo de valor) adecuada como clave para esa implementación de diccionario especializada en particular.

  • WPF no implementa diccionarios que requieren este uso. Las claves de objeto son más una característica general del lenguaje XAML, posiblemente útil para determinados escenarios de diccionario personalizados en los que es deseable crear el diccionario en XAML. En el caso de las características de WPF, como los estilos implícitos que usan claves que no son de cadena para los recursos, otras técnicas para establecer o especificar las claves existen, por lo que no es necesario usar una clave de objeto.

  • keyObject también podría ser un uso de extensión de marcado en forma de elemento de objeto, en lugar de una instancia de objeto directa.

Notas de uso de Silverlight

x:Key para Silverlight se documenta por separado. Para obtener más información, consulta características del lenguaje XAML (x:) (Silverlight).

Consulte también