Estensione di markup ThemeResource

Applies to Windows and Windows Phone

Fornisce un valore per qualsiasi attributo XAML tramite la valutazione di un riferimento a una risorsa, con logica di sistema aggiuntiva che recupera risorse diverse a seconda del tema attivo. Come avviene per StaticResource, le risorse sono definite in un oggetto ResourceDictionary e la sintassi di ThemeResource fa riferimento alla chiave di tale risorsa nell'oggettoResourceDictionary.

Sintassi degli attributi XAML

<object property="{ThemeResource key}" .../>

Valori XAML

TermineDescrizione

key

Chiave per la risorsa richiesta. Questa chiave viene inizialmente assegnata dall'attributo x:Key in una risorsa definita in una classe ResourceDictionary XAML. Una chiave di risorsa può essere qualsiasi stringa definita nella grammatica XamlName.

 

Osservazioni

ThemeResource è una tecnica che consente di ottenere i valori di un attributo XAML definiti altrove in un dizionario risorse XAML. Questa estensione di markup ha lo stesso scopo di base dell'estensione di markup StaticResource. La differenza di comportamento rispetto a StaticResource consiste nel fatto che un riferimento ThemeResource può utilizzare in modo dinamico dizionari diversi come posizione di ricerca principale, a seconda del tema attualmente utilizzato dal sistema.

All'avvio dell'app, qualsiasi riferimento a una risorsa effettuato da un riferimento ThemeResource viene valutato in base al tema in uso all'avvio. Tuttavia, se in seguito l'utente cambia il tema attivo in fase di esecuzione, il sistema ripete la valutazione di ogni singolo riferimento ThemeResource, recupera una risorsa specifica del tema, che può essere diversa, e rivisualizza l'app con i nuovi valori delle risorse in tutte le posizioni appropriate dell'albero visuale. L'oggetto StaticResource viene determinato al momento del caricamento di XAML o dell'avvio dell'app e non viene nuovamente valutato in fase di esecuzione. Esistono anche altre tecniche, come gli stati visivi, che ricaricano XAML in modo dinamico, ma tali tecniche operano a un livello più alto rispetto alla valutazione delle risorse di base abilitata da StaticResource).

ThemeResource accetta un singolo argomento, che specifica la chiave della risorsa richiesta. La chiave di una risorsa è sempre costituita da una stringa nell'implementazione XAML di Windows Runtime. Per ulteriori informazioni sull'impostazione iniziale della chiave di una risorsa, vedi Attributo x:Key.

Per ulteriori informazioni sulla definizione delle risorse e sull'uso corretto della classe ResourceDictionary, incluso il codice di esempio, vedi Riferimenti a ResourceDictionary e risorse XAML.

Importante  

Come con StaticResource, un'estensione ThemeResource non deve tentare di fare direttamente riferimento a una risorsa definita a livello lessicale più avanti all'interno del file XAML. I tentativi di questo tipo non sono supportati. Anche se il riferimento in avanti non riesce, il tentativo di eseguirlo determina un calo di prestazioni. Per ottenere risultati ottimali, devi regolare la composizione dei tuoi dizionari risorse in modo da poter evitare i riferimenti in avanti.

Il tentativo di specificare un oggetto ThemeResource per una chiave che non può essere risolta determina la generazione di un'eccezione nell'analisi XAML in fase di esecuzione. Gli strumenti di progettazione possono inoltre offrire avvisi o errori.

Nell'implementazione di XAML in Windows Runtime non è disponibile alcuna rappresentazione della classe di supporto per ThemeResource. L'equivalente più simile nel codice è costituito dall'uso di un'API di raccolta per un oggetto ResourceDictionary, ad esempio una chiamata a Contains o a TryGetValue.

ThemeResource è un'estensione di markup. Le estensioni del markup vengono in genere implementate quando bisogna ignorare che i valori di attributo non siano valori letterali o nomi di gestore e tale requisito è più globale rispetto alla semplice definizione di convertitori di tipi per determinati tipi o proprietà. Nella sintassi dell'attributo di tutte le estensioni del markup in XAML vengono usati i caratteri "{" e "}". Questa è la convenzione in base alla quale un processore XAML riconosce che un'estensione di markup deve elaborare l'attributo.

Quando e come utilizzare {ThemeResource} anziché {StaticResource}

Le regole utilizzate per risolvere un oggetto ThemeResource in un elemento di un dizionario risorse sono in genere le stesse utilizzate per StaticResource. Una ricerca tramite ThemeResource può estendersi nei file di ResourceDictionary a cui viene fatto riferimento in un insieme ThemeDictionaries, ma ciò è possibile anche tramite un'estensione StaticResource. La differenza consiste nel fatto che ThemeResource può ripetere la valutazione in fase di esecuzione, mentre StaticResource no.

L'insieme di chiavi in ogni dizionario dei temi deve fornire lo stesso insieme di risorse con chiave, indipendentemente dal tema attivo. Se nel dizionario dei temi HighContrast è presente una determinata risorsa con chiave, anche in Light e Default deve esistere un'altra risorsa con tale nome. In caso contrario, se l'utente cambia tema, la ricerca della risorsa potrebbe non riuscire e l'aspetto dell'app potrebbe non risultare corretto. Un dizionario dei temi potrebbe tuttavia contenere risorse con chiave a cui viene fatto riferimento solo dallo stesso ambito, per fornire valori secondari. In questo caso non devono necessariamente esistere risorse equivalenti in tutti i temi.

In generale, è consigliabile inserire le risorse nei dizionari dei temi e quindi fare riferimento a tali risorse tramite ThemeResource solo quando tali valori possono cambiare da un tema all'altro o sono supportati da valori modificabili. Questa tecnica è appropriata per i tipi di risorse seguenti:

  • Pennelli, in particolare i colori per SolidColorBrush. Queste risorse determinano circa l'80% degli utilizzi di ThemeResource nei modelli di controlli XAML predefiniti (generic.xaml).
  • Valori in pixel per bordi, offset, margini, riempimenti e così via.
  • Proprietà dei caratteri, quali FontFamily o FontSize.
  • Modelli completi per un numero limitato di controlli il cui stile viene in genere definito dal sistema e che vengono utilizzati per la presentazione dinamica, quali GridViewItem e ListViewItem.
  • Stili di visualizzazione del testo (in genere per modificare il colore, lo sfondo e se possibile la dimensione del carattere).

Windows Runtime offre un set di risorse sviluppate specificamente in modo che ThemeResource possa farvi riferimento. Queste risorse sono tutte elencate come parte del file XAML themeresources.xaml, disponibile nella cartella include/winrt/xaml/design di Windows Software Development Kit (SDK). Per la documentazione sui pennelli dei temi e altri stili definiti in themeresources.xaml, vedi Riferimento a risorse di tema XAML. I pennelli sono riportati in una tabella che indica il valore di colore associato a ciascun pennello per ognuno dei tre temi attivi possibili.

Le definizioni XAML degli stati visivi in un modello di controllo dovrebbero utilizzare riferimenti ThemeResource ogni volta che è presente una risorsa sottostante che potrebbe essere modificata in seguito a un cambiamento di tema. Il cambiamento di un tema di sistema in genere non determina anche la modifica di uno stato di visualizzazione. In questo caso le risorse devono utilizzare riferimenti ThemeResource, affinché sia possibile ripetere la valutazione dei valori per lo stato di visualizzazione ancora attivo. Se ad esempio è presente uno stato di visualizzazione che modifica un colore del pennello per una particolare area dell'interfaccia utente e una delle sue proprietà, e tale colore del pennello varia a seconda del tema, è necessario utilizzare un riferimento ThemeResource per fornire a tale modello predefinito il valore della proprietà nel modello predefinito, oltre a qualsiasi modifica dello stato di visualizzazione.

L'estensione ThemeResource può essere utilizzata in una serie di valori dipendenti. Ad esempio, un valore Color utilizzato da un oggetto SolidColorBrush e che è anche una risorsa con chiave potrebbe utilizzare un riferimento ThemeResource. Tuttavia, anche qualunque proprietà dell'interfaccia utente che utilizza la risorsa con chiave SolidColorBrush può utilizzare un riferimento ThemeResource, di modo che al cambiamento di tema la modifica dinamica del valore venga abilitata in modo specifico da ogni proprietà di tipo Brush.

Nota   L'estensione {ThemeResource} e la valutazione delle risorse in fase di esecuzione al cambiamento di tema sono supportate nella versione di XAML di Windows 8.1 ma non in quella per le app destinate a Windows 8.

Risorse di sistema

Alcune risorse dei temi fanno riferimento ai valori delle risorse di sistema come valori secondari sottostanti. Una risorsa di sistema è uno speciale valore di risorsa non disponibile in alcun dizionario risorse XAML. Tali valori si basano sul comportamento del supporto XAML di Windows Runtime per inoltrare valori dal sistema stesso e li rappresentano in un formato referenziabile da una risorsa XAML. Ad esempio, esiste una risorsa di sistema di nome "SystemColorButtonFaceColor", che rappresenta un colore RGB. Tale colore proviene dagli aspetti di colori e temi di sistema che non sono specifici solo di Windows Runtime e delle app di Windows Runtime.

Le risorse di sistema costituiscono spesso i valori sottostanti per i temi a contrasto elevato. L'utente può controllare la scelta dei colori per il tema a contrasto elevato e, per effettuare tale scelta, usa funzionalità di sistema che non sono specifiche delle app di Windows Runtime. Specificando le risorse di sistema come riferimenti ThemeResource, il comportamento predefinito dei temi a contrasto elevato per le app di Windows Runtime può usare i valori specifici del tema controllati dall'utente ed esposti dal sistema. Inoltre, ora i riferimenti vengono contrassegnati per ripetere la valutazione quando il sistema rileva un cambiamento di tema in fase di esecuzione.

Esempio di utilizzo di {ThemeResource}

Di seguito è riportato un esempio su XAML, tratto dai file predefiniti generic.xaml e themeresources.xaml, per illustrare l'utilizzo di ThemeResource. Esamineremo solo un modello (il modello Button predefinito) e il modo in cui due proprietà (Background e Foreground) vengono dichiarate affinché rispondano ai cambiamenti di tema.


    <!-- Default style for Windows.UI.Xaml.Controls.Button -->
    <Style TargetType="Button">
        <Setter Property="Background" Value="{ThemeResource ButtonBackgroundThemeBrush}" />
        <Setter Property="Foreground" Value="{ThemeResource ButtonForegroundThemeBrush}"/>
...

In questo caso le proprietà accettano un valore Brush e i riferimenti alle risorse SolidColorBrush di nome ButtonBackgroundThemeBrush e ButtonForegroundThemeBrush vengono effettuati tramite ThemeResource.

Le stesse proprietà vengono modificate anche per alcuni degli stati di visualizzazione di un controllo Button. In particolare, il colore di sfondo cambia quando viene fatto clic su un pulsante. Anche in questo caso, le animazioni Background e Foreground nello storyboard dello stato di visualizzazione utilizzano oggetti DiscreteObjectKeyFrame e riferimenti a pennelli con ThemeResource come valore del fotogramma chiave.


<VisualState x:Name="Pressed">
  <Storyboard>
    <ObjectAnimationUsingKeyFrames Storyboard.TargetName="Border"
        Storyboard.TargetProperty="Background">
      <DiscreteObjectKeyFrame KeyTime="0" Value="{ThemeResource ButtonPressedBackgroundThemeBrush}" />
    </ObjectAnimationUsingKeyFrames>
    <ObjectAnimationUsingKeyFrames Storyboard.TargetName="ContentPresenter"
         Storyboard.TargetProperty="Foreground">
       <DiscreteObjectKeyFrame KeyTime="0" Value="{ThemeResource ButtonPressedForegroundThemeBrush}" />
    </ObjectAnimationUsingKeyFrames>
  </Storyboard>
</VisualState>

Ciascuno di tali pennelli è stato definito in precedenza in generic.xaml. I pennelli devono essere infatti definiti prima di qualsiasi modello che li utilizza, per evitare riferimenti XAML in avanti. Di seguito sono riportate tali definizioni per il dizionario dei temi "Default".


    <ResourceDictionary.ThemeDictionaries>
        <ResourceDictionary x:Key="Default">
... 
            <SolidColorBrush x:Key="ButtonBackgroundThemeBrush" Color="Transparent" />
            <SolidColorBrush x:Key="ButtonForegroundThemeBrush" Color="#FFFFFFFF" />
...
            <SolidColorBrush x:Key="ButtonPressedBackgroundThemeBrush" Color="#FFFFFFFF" />
            <SolidColorBrush x:Key="ButtonPressedForegroundThemeBrush" Color="#FF000000" />
...

Tali pennelli sono definito anche in tutti gli altri dizionari dei temi, ad esempio:


        <ResourceDictionary x:Key="HighContrast">
            <!-- High Contrast theme resources -->
...
            <SolidColorBrush x:Key="ButtonBackgroundThemeBrush" Color="{ThemeResource SystemColorButtonFaceColor}" />
            <SolidColorBrush x:Key="ButtonForegroundThemeBrush" Color="{ThemeResource SystemColorButtonTextColor}" />

...
            <SolidColorBrush x:Key="ButtonPressedBackgroundThemeBrush" Color="{ThemeResource SystemColorButtonTextColor}" />
            <SolidColorBrush x:Key="ButtonPressedForegroundThemeBrush" Color="{ThemeResource SystemColorButtonFaceColor}" />

In questo caso il valore Color è un altro riferimento ThemeResource a una risorsa di sistema. Se si fa riferimento a una risorsa di sistema e si desidera che venga modificata in risposta a un cambiamento di tema, è necessario utilizzare ThemeResource per creare il riferimento.

Comportamento di Windows 8

Windows 8 non supporta l'estensione di markup ThemeResource. Questa estensione è disponibile a partire da Windows 8.1. Windows 8 inoltre non supporta lo scambio dinamico delle risorse relative ai temi per un'app di Windows Runtime. È necessario riavviare l'app per rendere effettivo il cambiamento dei temi per gli stili e i modelli XAML. Non si tratta di un'esperienza utente positiva, perciò è consigliabile ricompilare le app in funzione di Windows 8.1 in modo che possano usare gli stili con ThemeResource e possano cambiare dinamicamente i temi in contemporanea con l'utente. Le app create per Windows 8 che vengono eseguite in Windows 8.1 continuano a usare il comportamento di Windows 8.

Supporto dell'estensione di markup {ThemeResource} negli strumenti di progettazione

Microsoft Visual Studio 2013 può includere i valori possibili per le chiavi negli elenchi a discesa di Microsoft IntelliSense quando usi l'estensione di markup {ThemeResource} in una pagina XAML. Ad esempio, non appena digiti "{ThemeResource", vengono visualizzate le eventuali chiavi di risorse dalle risorse del tema.

Quando una chiave di risorsa esiste come parte di qualsiasi utilizzo {ThemeResource}, la funzionalità Vai a definizione (F12) può risolvere tale risorsa e mostrare il file generic.xaml per la fase di progettazione, in cui viene definita la risorsa del tema. Dato che le risorse del tema vengono definite più di una volta (per tema), Vai a definizione porta alla prima definizione trovata nel file, ovvero la definizione per Default. Se vuoi le altre definizioni, puoi cercare il nome della chiave nel file per trovare le altre definizioni del tema.

Argomenti correlati

Riferimenti a ResourceDictionary e risorse XAML
Riferimento a risorse di tema XAML
ResourceDictionary
Attributo x:Key

 

 

Mostra:
© 2014 Microsoft