Diretiva x:Key

Identifica exclusivamente elementos que são criados e referenciados em um dicionário definido por XAML. Adicionar um valor a um elemento de objeto XAML é a maneira mais comum de identificar um recurso em um dicionário de recursos, por exemplo, em um x:Key WPF ResourceDictionary.

Uso do Atributo XAML

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

Uso de atributo XAML (específico do WPF)

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

Valores XAML

Comentários

x:Key dá suporte ao conceito de dicionário de recursos XAML. O XAML como uma linguagem não define uma implementação de dicionário de recursos, que é deixada para estruturas de interface do usuário específicas. Para saber mais sobre como os dicionários de recursos XAML são implementados no WPF, consulte Visão geral dos recursos XAML (WPF .NET).

Em XAML 2006 e WPF, x:Key deve ser fornecido como um atributo. Você ainda pode usar chaves que não sejam string, mas isso requer um uso de extensão de marcação para fornecer o valor nonstring no formato de atributo. Se você estiver usando XAML 2009, x:Key pode ser especificado como um elemento , para oferecer suporte explícito a dicionários chaveados por tipos de objeto diferentes de cadeias de caracteres sem exigir uma extensão de marcação intermediária. Consulte a seção "XAML 2009" neste tópico. O restante da seção Comentários se aplica especificamente à implementação do XAML 2006.

O valor do atributo de pode ser qualquer cadeia de caracteres definida na Gramática XamlName ou pode ser um objeto avaliado por meio de uma extensão de x:Key marcação. Consulte "Notas de uso do WPF" para obter um exemplo do WPF.

Os elementos filho de um elemento pai que é uma IDictionary implementação normalmente devem incluir um atributo que especifica um x:Key valor de chave exclusivo dentro desse dicionário. As estruturas podem implementar propriedades de chave aliased para substituir x:Key em tipos específicos, os tipos que definem tais propriedades devem ser atribuídos a DictionaryKeyPropertyAttribute.

O código equivalente de especificar x:Key é a chave usada para o IDictionary. Por exemplo, um que é aplicado na marcação para um recurso no WPF é equivalente ao valor do key parâmetro de ResourceDictionary.Add quando você adiciona o recurso a um x:Key WPF ResourceDictionary no código.

Notas de uso do WPF

Os objetos filho de um objeto pai que é uma IDictionary implementação, como o WPF ResourceDictionary, normalmente devem incluir um x:Key atributo e o valor da chave deve ser exclusivo nesse dicionário. Há duas exceções notáveis:

• Alguns tipos de WPF declaram uma chave implícita para uso no dicionário. Por exemplo, um com um , ou um com um , pode estar em um StyleDataTypeTargetTypeDataTemplateResourceDictionary e usar a chave implícita.

• O WPF oferece suporte a um conceito de dicionário de recursos mesclados. As chaves podem ser compartilhadas entre os dicionários mesclados e o comportamento da chave compartilhada pode ser acessado usando FindResourceo . Para obter mais informações, consulte Dicionários de recursos mesclados.

Na implementação geral do WPF XAML e no modelo de aplicativo, a exclusividade da chave não é verificada pelo compilador de marcação XAML. Em vez disso, valores ausentes ou não exclusivos x:Key causam erros de analisador XAML em tempo de carregamento. No entanto, o Visual Studio manipulação de dicionários para WPF muitas vezes pode observar esses erros na fase de design.

Observe que, na sintaxe mostrada, o objeto está implícito em como o ResourceDictionary processador XAML do WPF produz uma coleção para preencher uma Resources coleção. A ResourceDictionary normalmente não é fornecido explicitamente como um elemento na marcação, embora possa ser em alguns casos se desejado para clareza (seria um elemento de objeto de coleção entre o elemento de propriedade e os itens dentro que preenchem o Resources dicionário). Para obter informações sobre por que um objeto de coleção é quase sempre um elemento implícito na marcação, consulte Sintaxe XAML em detalhes.

Na implementação XAML do WPF, a manipulação de chaves de dicionário de recursos é definida pela ResourceKey classe abstrata. No entanto, o processador XAML do WPF produz diferentes tipos de extensão subjacentes para chaves com base em seus usos. Por exemplo, a chave para uma DataTemplate ou qualquer classe derivada é tratada separadamente e produz um objeto distinto DataTemplateKey .

Chaves e nomes usam diretivas e elementos de linguagem diferentes (x:Keyx:Nameversus ) na definição básica de XAML. Chaves e nomes também são usados em diferentes situações pela definição e aplicação desses conceitos do WPF. Para obter detalhes, consulte Namescopes XAML do WPF.

Como dito anteriormente, o valor de uma chave pode ser fornecido por meio de uma extensão de marcação e pode ser diferente de um valor de cadeia de caracteres. Um exemplo de cenário WPF é que o valor de x:Key pode ser um ComponentResourceKey. Determinados controles expõem uma chave de estilo desse tipo para um recurso de estilo personalizado que influencia parte da aparência e do comportamento desse controle sem substituir totalmente o estilo. Um exemplo de tal chave é ButtonStyleKey.

O recurso de dicionário mesclado do WPF introduz considerações adicionais para exclusividade de chave e comportamento de pesquisa de chave. Para obter mais informações, consulte Dicionários de recursos mesclados.

XAML 2009

O XAML 2009 relaxa a restrição que x:Key sempre será fornecida no formato de atributo.

No WPF, você pode usar recursos XAML 2009, mas somente para XAML que não é compilado por marcação. Atualmente, o XAML compilado por marcação para WPF e a forma BAML de XAML não oferecem suporte às palavras-chave e aos recursos do XAML 2009.

Em XAML 2009, você pode especificar x:Key elementos por meio do seguinte uso:

Uso do elemento XAML (somente XAML 2009)

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

Valores XAML

• O contêiner/pai para esse tipo de uso não é mostrado aqui. object espera-se que seja filho de um elemento de objeto que representa uma implementação de dicionário especializado. keyObject espera-se que seja uma instância de objeto (ou um valor de um tipo de valor) que seja apropriada como a chave para essa implementação de dicionário especializado específica.

• O WPF não implementa dicionários que exijam esse uso. As chaves de objeto são mais um recurso geral da linguagem XAML, possivelmente útil para determinados cenários de dicionário personalizados em que a criação do dicionário em XAML é desejável. Para recursos do WPF, como estilos implícitos que usam chaves que não são de cadeia de caracteres para recursos, existem outras técnicas para estabelecer ou especificar as chaves, portanto, o uso de uma chave de objeto não é necessário.

• keyObject também pode ser um uso de extensão de marcação no formato de elemento de objeto, em vez de uma instância de objeto direto.

Notas de uso do Silverlight

x:Key para o Silverlight é documentado separadamente. Para obter mais informações, consulte Recursos de linguagem do namespace XAML (x:) (Silverlight).

Confira também

• Visão geral dos recursos XAML (WPF .NET)
• Recursos em código (WPF .NET)
• Extensão de marcação StaticResource