Condividi tramite

Direttiva x:Key

  • Articolo

Identifica in modo univoco gli elementi creati e a cui viene fatto riferimento in un dizionario definito da XAML. L'aggiunta di un x:Key valore a un elemento oggetto XAML è il modo più comune per identificare una risorsa in un dizionario risorse, ad esempio in un oggetto WPF ResourceDictionary.

Uso della sintassi XAML per gli attributi

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

Utilizzo degli attributi XAML (specifico di WPF)

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

Valori XAML

Valore Descrizione
stringKeyValue Stringa di testo da usare come chiave. La stringa di testo deve essere conforme alla grammatica XamlName.
markupExtensionUsage All'interno dei delimitatori {}di estensione di markup , un utilizzo dell'estensione di markup che fornisce un oggetto da usare come chiave. Vedere la sezione Osservazioni.

Osservazioni

x:Key supporta il concetto di dizionario risorse XAML. XAML come linguaggio non definisce un'implementazione del dizionario risorse, lasciata a framework dell'interfaccia utente specifici. Per altre informazioni sull'implementazione dei dizionari risorse XAML in WPF, vedere Panoramica delle risorse XAML (WPF .NET).

In XAML 2006 e WPF deve x:Key essere specificato come attributo. È comunque possibile usare chiavi nonstring, ma questo richiede un utilizzo dell'estensione di markup per fornire il valore non distring in formato attributo. Se usi XAML 2009, x:Key puoi essere specificato come elemento per supportare in modo esplicito i dizionari con chiave in base ai tipi di oggetto diversi dalle stringhe senza richiedere un'estensione di markup intermedia. Vedere la sezione "XAML 2009" in questo argomento. La parte restante della sezione Osservazioni si applica in modo specifico all'implementazione XAML 2006.

Il valore dell'attributo di x:Key può essere qualsiasi stringa definita nella grammatica XamlName o può essere un oggetto valutato tramite un'estensione di markup. Per un esempio di WPF, vedere "Note sull'utilizzo di WPF".

Gli elementi figlio di un elemento padre che è un'implementazione IDictionary devono in genere includere un x:Key attributo che specifica un valore di chiave univoco all'interno di tale dizionario. I framework potrebbero implementare proprietà chiave con alias da sostituire con x:Key tipi specifici. I tipi che definiscono tali proprietà devono essere attribuiti con DictionaryKeyPropertyAttribute.

L'equivalente del codice di specifica è x:Key la chiave usata per l'oggetto sottostante IDictionary. Ad esempio, un oggetto x:Key applicato nel markup per una risorsa in WPF equivale al valore del parametro di keyResourceDictionary.Add quando si aggiunge la risorsa a un wpf ResourceDictionary nel codice.

Note sull'utilizzo di WPF

Gli oggetti figlio di un oggetto padre che è un'implementazione IDictionary , ad esempio WPF ResourceDictionary, devono in genere includere un x:Key attributo e il valore della chiave deve essere univoco all'interno di tale dizionario. Esistono due eccezioni rilevanti:

  • Alcuni tipi WPF dichiarano una chiave implicita per l'utilizzo del dizionario. Ad esempio, un Style oggetto con un TargetTypeoggetto o DataTemplate con un DataTypeoggetto , può trovarsi in un ResourceDictionary oggetto e usare la chiave implicita.

  • WPF supporta un concetto di dizionario risorse unito. Le chiavi possono essere condivise tra i dizionari uniti e il comportamento della chiave condivisa è accessibile tramite FindResource. Per altre informazioni, vedere Dizionari risorse uniti.

Nell'implementazione XAML WPF complessiva e nel modello di applicazione, l'univocità della chiave non viene controllata dal compilatore di markup XAML. Al contrario, i valori mancanti o non univoci x:Key causano errori del parser XAML in fase di caricamento. Tuttavia, la gestione di visual Studio dei dizionari per WPF spesso può notare tali errori nella fase di progettazione.

Si noti che nella sintassi mostrata l'oggetto ResourceDictionary è implicito nel modo in cui il processore XAML WPF produce una raccolta per popolare una Resources raccolta. Un ResourceDictionary oggetto non viene in genere fornito in modo esplicito come elemento nel markup, anche se può essere in alcuni casi se si vuole maggiore chiarezza (si tratta di un elemento oggetto raccolta tra l'elemento Resources della proprietà e gli elementi all'interno di che popolano il dizionario). Per informazioni sul motivo per cui un oggetto raccolta è quasi sempre un elemento implicito nel markup, vedi Sintassi XAML in dettaglio.

Nell'implementazione XAML WPF la gestione delle chiavi del dizionario risorse viene definita dalla ResourceKey classe astratta. Tuttavia, il processore XAML WPF produce tipi di estensione sottostanti diversi per le chiavi in base ai relativi utilizzi. Ad esempio, la chiave per una DataTemplate classe derivata o viene gestita separatamente e produce un oggetto distinto DataTemplateKey .

Le chiavi e i nomi usano direttive ed elementi del linguaggio diversi ( rispettox:Keyx:Namea ) nella definizione XAML di base. Le chiavi e i nomi vengono usati anche in situazioni diverse dalla definizione e dall'applicazione WPF di questi concetti. Per informazioni dettagliate, vedere Ambiti dei nomi XAML WPF.

Come indicato in precedenza, il valore di una chiave può essere fornito tramite un'estensione di markup e può essere diverso da un valore stringa. Uno scenario WPF di esempio è che il valore di x:Key può essere ComponentResourceKey. Alcuni controlli espongono una chiave di stile di tale tipo per una risorsa di stile personalizzata che influenza parte dell'aspetto e del comportamento di tale controllo senza sostituire completamente lo stile. Un esempio di chiave di questo tipo è ButtonStyleKey.

La funzionalità del dizionario unito WPF introduce considerazioni aggiuntive per l'univocità delle chiavi e il comportamento di ricerca delle chiavi. Per altre informazioni, vedere Dizionari risorse uniti.

XAML 2009

XAML 2009 riduce la restrizione sempre x:Key fornita in formato attributo.

In WPF puoi usare le funzionalità XAML 2009, ma solo per XAML che non è compilato con markup. Il codice XAML compilato dal markup per WPF e il modulo BAML di XAML non supportano attualmente le parole chiave e le funzionalità di XAML 2009.

In XAML 2009 puoi specificare x:Key gli elementi tramite l'utilizzo seguente:

Utilizzo elementi XAML (solo XAML 2009)

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

Valori XAML

Valore Descrizione
keyObject Elemento Object per l'oggetto utilizzato come chiave per un oggetto specificato object in un dizionario specializzato.

  • Il contenitore/elemento padre per questo tipo di utilizzo non è illustrato qui. object deve essere un elemento figlio di un elemento oggetto che rappresenta un'implementazione specializzata del dizionario. keyObject deve essere un'istanza dell'oggetto (o un valore di un tipo valore) appropriata come chiave per tale implementazione specializzata del dizionario.

  • WPF non implementa dizionari che richiedono questo utilizzo. Le chiavi oggetto sono più una funzionalità generale del linguaggio XAML, possibilmente utile per alcuni scenari di dizionario personalizzati in cui è consigliabile creare il dizionario in XAML. Per le funzionalità WPF, ad esempio gli stili impliciti che usano chiavi non stringa per le risorse, altre tecniche per stabilire o specificare le chiavi esistono, pertanto l'uso di una chiave oggetto non è necessario.

  • keyObject potrebbe anche essere un utilizzo dell'estensione di markup nel formato dell'elemento oggetto, anziché un'istanza diretta dell'oggetto.

Note sull'utilizzo di Silverlight

x:Key per Silverlight è documentato separatamente. Per altre informazioni, vedere Funzionalità del linguaggio dello spazio dei nomi XAML (x:) (Silverlight).

Vedi anche