x:Key (Directiva)x:Key Directive

Identifica de forma única los elementos que se crean y a los que se hace referencia en un diccionario definido por XAML.Uniquely identifies elements that are created and referenced in a XAML-defined dictionary. Agregar un x:Key valor a un elemento de objeto XAML es la forma más común de identificar un recurso en un diccionario de recursos, por ejemplo en ResourceDictionaryun WPF.Adding an x:Key value to a XAML object element is the most common way to identify a resource in a resource dictionary, for example in a WPF ResourceDictionary.

Uso de atributos XAMLXAML Attribute Usage

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

Uso de atributos XAML (específicos de WPF)XAML Attribute Usage (WPF-specific)

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

Valores XAMLXAML Values

stringKeyValue Cadena de texto que se va a usar como clave.A text string to use as a key. La cadena de texto debe ajustarse a la Gramática XamlName.The text string must conform to the XamlName Grammar.
markupExtensionUsage Dentro de los delimitadores {}de la extensión de marcado, un uso de la extensión de marcado que proporciona un objeto que se va a usar como clave.Within the markup extension delimiters {}, a markup extension usage that provides an object to use as a key. Vea la sección Comentarios.See Remarks.

ComentariosRemarks

x:Keyadmite el concepto de Diccionario de recursos XAML.x:Key supports the XAML resource dictionary concept. XAML como lenguaje no define una implementación de Diccionario de recursos, que se deja en marcos de interfaz de usuario específicos.XAML as a language doesn't define a resource dictionary implementation, that is left to specific UI frameworks. Para obtener más información sobre cómo se implementan los diccionarios de recursos XAML en WPF, vea recursos XAML.To learn more about how XAML resource dictionaries are implemented in WPF, see XAML Resources.

En XAML 2006 y WPF, x:Key se debe proporcionar como un atributo.In XAML 2006 and WPF, x:Key must be provided as an attribute. Todavía puede usar claves que no sean de cadena, pero esto requiere un uso de la extensión de marcado para proporcionar el valor no de cadena en el formato de atributo.You can still use nonstring keys, but this requires a markup extension usage in order to provide the nonstring value in attribute form. Si usa XAML 2009, x:Key se puede especificar como un elemento para admitir explícitamente diccionarios con clave de tipos de objeto que no sean cadenas sin requerir una extensión de marcado intermedia.If you are using XAML 2009, x:Key can be specified as an element, to explicitly support dictionaries keyed by object types other than strings without requiring a markup extension intermediate. Vea la sección "XAML 2009" en este tema.See the "XAML 2009" section in this topic. El resto de la sección comentarios se aplica específicamente a la implementación de XAML 2006.The remainder of the Remarks section applies specifically to the XAML 2006 implementation.

El valor del atributo x:Key de puede ser cualquier cadena definida en la gramática de XamlName o puede ser un objeto evaluado a través de una extensión de marcado.The attribute value of x:Key can be any string defined in the XamlName Grammar or can be an object evaluated through a markup extension. Vea "Notas de uso de WPF" para obtener un ejemplo de WPF.See "WPF Usage Notes" for an example from WPF.

Los elementos secundarios de un elemento primario que es IDictionary una implementación de deben incluir x:Key normalmente un atributo que especifica un valor de clave único dentro de ese diccionario.Child elements of a parent element that is an IDictionary implementation must typically include an x:Key attribute that specifies a unique key value within that dictionary. Los marcos de trabajo pueden implementar propiedades de clave con alias x:Key para sustituirlos en determinados tipos; los tipos que definen dichas propiedades DictionaryKeyPropertyAttributedeben tener el atributo.Frameworks might implement aliased key properties to substitute for x:Key on particular types; types that define such properties should be attributed with DictionaryKeyPropertyAttribute.

El equivalente de código de especificar x:Key es la clave que se usa para el subyacente IDictionary.The code equivalent of specifying x:Key is the key that is used for the underlying IDictionary. Por ejemplo, un x:Key que se aplica en el marcado para un recurso en WPF es equivalente al valor key del parámetro de ResourceDictionary.Add cuando se agrega el recurso a WPF ResourceDictionary en código.For example, an x:Key that is applied in markup for a resource in WPF is equivalent to the value of the key parameter of ResourceDictionary.Add when you add the resource to a WPF ResourceDictionary in code.

Notas de uso de WPFWPF Usage Notes

Los objetos secundarios de un objeto primario que es IDictionary una implementación de, como WPF ResourceDictionary, normalmente deben incluir un x:Key atributo y el valor de clave debe ser único dentro de ese diccionario.Child objects of a parent object that is an IDictionary implementation, such as the WPF ResourceDictionary, must typically include an x:Key attribute, and the key value must be unique within that dictionary. Hay dos excepciones importantes:There are two notable exceptions:

  • Algunos tipos de WPF declaran una clave implícita para el uso del diccionario.Some WPF types declare an implicit key for dictionary usage. Por Style ejemplo, DataTemplate con TargetType, o con ResourceDictionary , puede estar en y usar la clave implícita. DataTypeFor example, a Style with a TargetType, or a DataTemplate with a DataType, can be in a ResourceDictionary and use the implicit key.

  • WPF admite un concepto de Diccionario de recursos combinados.WPF supports a merged resource dictionary concept. Las claves se pueden compartir entre los diccionarios combinados y se puede tener acceso al comportamiento de la clave compartida FindResourcemediante.Keys can be shared between the merged dictionaries, and the shared key behavior can be accessed using FindResource. Para más información, consulte Merged Resource Dictionaries (Diccionarios de recursos combinados).For more information, see Merged Resource Dictionaries.

En el modelo de aplicación y la implementación XAML de WPF generales, el compilador de marcado XAML no comprueba la unicidad de la clave.In the overall WPF XAML implementation and application model, key uniqueness is not checked by the XAML markup compiler. En su lugar, los valores que x:Key faltan o no son únicos causan errores del analizador de XAML en tiempo de carga.Instead, missing or nonunique x:Key values cause load-time XAML parser errors. Sin embargo, el control de los diccionarios de WPF en Visual Studio a menudo puede tener en cuenta estos errores en la fase de diseño.However, Visual Studio handling of dictionaries for WPF can often note such errors in the design phase.

Tenga en cuenta que en la sintaxis mostrada, el ResourceDictionary objeto está implícito en cómo el procesador XAML de WPF genera una colección para rellenar una Resources colección.Note that in the syntax shown, the ResourceDictionary object is implicit in how the WPF XAML processor produces a collection to populate a Resources collection. Normalmente, no Resources seproporcionaexplícitamentecomounelementoenelmarcado,aunquepuedeserenalgunoscasossisedeseaparamayorclaridad(seríaunelementodeobjetodecolecciónentreelelementodepropiedadyloselementosdequeResourceDictionary rellenan la Diccionario).A ResourceDictionary is not typically provided explicitly as an element in markup, although it can be in some cases if wanted for clarity (it would be a collection object element between the Resources property element and the items within that populate the dictionary). Para obtener información sobre por qué un objeto de colección casi siempre es un elemento implícito en el marcado, vea la Sintaxis de XAML en detalle.For information about why a collection object is almost always an implicit element in markup, see XAML Syntax In Detail.

En la implementación XAML de WPF, el control de las claves de Diccionario de recursos ResourceKey se define mediante la clase abstracta.In the WPF XAML implementation, the handling for resource dictionary keys is defined by the ResourceKey abstract class. Sin embargo, el procesador XAML de WPF genera distintos tipos de extensión subyacentes para las claves en función de sus usos.However the WPF XAML processor produces different underlying extension types for keys based on their usages. Por ejemplo, la clave de un DataTemplate objeto o cualquier clase derivada se administra por separado y genera un objeto DataTemplateKey distinto.For example, the key for a DataTemplate or any derived class is handled separately, and produces a distinct DataTemplateKey object.

Las claves y los nombres usan directivas y elementos dex:Key lenguaje x:Namediferentes (frente a) en la definición básica de XAML.Keys and names use different directives and language elements (x:Key versus x:Name) in the basic XAML definition. La definición y la aplicación de estos conceptos también usan claves y nombres en diferentes situaciones.Keys and names are also used in different situations by the WPF definition and application of these concepts. Para obtener más información, vea ámbitos de código XAML de WPF.For details, see WPF XAML Namescopes.

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.As stated previously, the value of a key can be supplied through a markup extension and can be other than a string value. Un escenario de ejemplo de WPF es que el x:Key valor de puede ser un ComponentResourceKey.An example WPF scenario is that the value of x:Key may be a ComponentResourceKey. Ciertos 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 completamente el estilo.Certain controls expose a style key of that type for a custom style resource that influences part of the appearance and behavior of that control without totally replacing the style. Un ejemplo de este tipo de clave ButtonStyleKeyes.An example of such a key is ButtonStyleKey.

La característica de diccionario combinado de WPF presenta consideraciones adicionales para la singularidad clave y el comportamiento de búsqueda de claves.The WPF merged dictionary feature introduces additional considerations for key uniqueness and key lookup behavior. Para más información, consulte Merged Resource Dictionaries (Diccionarios de recursos combinados).For more information, see Merged Resource Dictionaries.

XAML 2009XAML 2009

XAML 2009 relaja la restricción que x:Key siempre se proporciona en forma de atributo.XAML 2009 relaxes the restriction that x:Key always be provided in attribute form.

En WPF, puede usar las características de XAML 2009, pero solo para XAML que no está compilado por marcado.In WPF, you can use XAML 2009 features, but only for XAML that is not markup-compiled. XAML compilado por marcado para WPF y el formulario BAML de XAML no admiten de momento las palabras clave y características de XAML 2009.Markup-compiled XAML for WPF and the BAML form of XAML do not currently support the XAML 2009 keywords and features.

En XAML 2009, puede especificar x:Key elementos mediante el siguiente uso:Under XAML 2009, you can specify x:Key elements through the following usage:

Uso de elementos XAML (solo XAML 2009)XAML Element Usage (XAML 2009 only)

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

Valores XAMLXAML Values

keyObject Elemento de objeto para el objeto que se utiliza como clave para un determinado object en un diccionario especializado.Object element for the object that is used as the key for a given object in a specialized dictionary.
  • El contenedor/elemento primario para este tipo de uso no se muestra aquí.The container/parent for this kind of use is not shown here. objectse espera que sea un elemento secundario de un elemento de objeto que representa una implementación de diccionario especializada.object is expected to be a child of an object element that represents a specialized dictionary implementation. keyObjectse espera que sea una instancia de objeto (o un valor de un tipo de valor) que sea adecuada como clave para esa implementación concreta de diccionario especializado.keyObject is expected to be an object instance (or a value of a value type) that is appropriate as the key for that particular specialized dictionary implementation.

  • WPF no implementa diccionarios que requieran este uso.WPF does not implement dictionaries that require this usage. Las claves de objeto son más una característica general del lenguaje XAML, que probablemente resulta útil para ciertos escenarios de diccionario personalizado en los que es deseable crear el Diccionario en XAML.Object keys is more a general feature of the XAML language, possibly useful for certain custom dictionary scenarios where creating the dictionary in XAML is desirable. 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, existen otras técnicas de establecimiento o especificación de las claves, por lo que no es necesario usar una clave de objeto.For WPF features such as implicit styles that use non-string keys for resources, other techniques for establishing or specifying the keys exist, so using an object key is not necessary.

  • keyObject también podría ser un uso de la extensión de marcado en el formulario de elemento de objeto, en lugar de una instancia de objeto directa.keyObject could also be a markup extension usage in object element form, rather than a direct object instance.

Notas de uso de SilverlightSilverlight Usage Notes

x:Keypara Silverlight se documenta por separado.x:Key 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