ResourceDictionary Classe

Riferimento

Definizione

Spazio dei nomi:: Windows.UI.Xaml

Importante

Alcune informazioni sono relative alla release non definitiva del prodotto, che potrebbe subire modifiche significative prima della release definitiva. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

Modifica

Definisce un repository per le risorse XAML, ad esempio gli stili, usati dall'app. Definisci le risorse in XAML e puoi recuperarle in XAML usando l'estensione di markup {StaticResource} e l'estensione di markup {ThemeResource} . È anche possibile accedere alle risorse con codice, ma questo è meno comune.

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class ResourceDictionary : DependencyObject, IIterable<IKeyValuePair<IInspectable, IInspectable const&>>, IMap<IInspectable, IInspectable const&>

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public class ResourceDictionary : DependencyObject, IDictionary<object,object>, IEnumerable<KeyValuePair<object,object>>

Public Class ResourceDictionary
Inherits DependencyObject
Implements IDictionary(Of Object, Object), IEnumerable(Of KeyValuePair(Of Object, Object))

<ResourceDictionary>
  oneOrMoreResources
</ResourceDictionary>
- or -
<frameworkElement>
  <frameworkElement.Resources>
    oneOrMoreResources
  </frameworkElement.Resources>
</frameworkElement>

Ereditarietà: Object IInspectable DependencyObject ResourceDictionary

Derivato: Windows.UI.Xaml.ColorPaletteResources

Attributi: ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Implementazioni: IDictionary<Object,Object> IMap<IInspectable,IInspectable> IIterable<IKeyValuePair<K,V>> IEnumerable<KeyValuePair<K,V>> IEnumerable<KeyValuePair<Object,Object>> IIterable<IKeyValuePair<IInspectable,IInspectable>>

Requisiti Windows

Famiglia di dispositivi	Windows 10 (è stato introdotto in 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (è stato introdotto in v1.0)

Commenti

Un dizionario risorse è un repository per le risorse XAML, ad esempio stili, che l'app usa. Definire le risorse in XAML e recuperarle in XAML usando l'estensione di markup {StaticResource} e {ThemeResource}markup s . È anche possibile accedere alle risorse con il codice, ma è meno comune. È possibile usare le risorse per applicare determinati valori, ad esempio i colori del pennello o le misurazioni pixel, vengono usati in modo coerente in tutta l'app. Per altre informazioni sull'uso dei dizionari delle risorse in modo efficace, vedere Riferimenti alle risorse ResourceDictionary e XAML.

Utilizzo degli elementi ResourceDictionary

Il tipo ResourceDictionary viene usato come valore di due proprietà, FrameworkElement.Resources e Application.Resources, importanti per la struttura complessiva di un'app UWP. I file XAML che si ottengono da un modello di progetto iniziale per un'app inizieranno con i valori iniziali per FrameworkElement.Resources e il file app.xaml potrebbe iniziare con valori iniziali per Application.Resources. Esattamente le risorse definite dipendono dal modello di avvio del progetto in uso.

Questo XAML mostra l'uso di una proprietà FrameworkElement.Resources . In questo caso FrameworkElement è una pagina. Non esiste alcun elemento ResourceDictionary subordinato all'elemento proprietà Page.Resources, ma la sua presenza è implicita; per altre informazioni, vedere la sezione "Note sulla sintassi XAML" di seguito. Xaml inserisce uno stile nel ResourceDictionary con un valore di attributo x:Key di "TextBlockStyle1". Più avanti in XAML, l'estensione di markup {StaticResource} fa riferimento allo stile nel dizionario risorse per fornire un valore per la proprietà Style dell'elemento TextBlock .

Lo stile , come illustrato, non applica effettivamente alcun stile a TextBlock, ma è possibile aggiungere proprietà Style in Microsoft Visual Studio. È quindi possibile usare la risorsa Stile come si vuole nella pagina per applicare l'uniformità.

È possibile usare Microsoft Visual Studio per creare dizionari di risorse. Questo esempio è stato creato con questi passaggi: inserire textBlock nell'area di progettazione, fare clic con il pulsante destro del mouse, scegliere Modifica stile /Crea vuoto, quindi "Questo documento" per definire la nuova risorsa in Page.Resources.

<Page
    x:Class="ResourceDictionary_example.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:ResourceDictionary_example"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d">
    <Page.Resources>
        <Style x:Key="TextBlockStyle1" TargetType="TextBlock"/>
    </Page.Resources>

    <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
        <TextBlock Style="{StaticResource TextBlockStyle1}" Text="TextBlock"/>
    </Grid>
</Page>

Questo codice XAML, dal file AppPage.xaml dell'esempio AtomPub, mostra l'uso di una proprietà Application.Resources . XAML inserisce due elementi Style nel dizionario risorse, rendendoli disponibili in tutta l'applicazione.

<Application xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
    x:Class="AtomPub.App"
    RequestedTheme="Light" >
    <Application.Resources>
        <ResourceDictionary>
            <Style x:Key="TitleStyle" TargetType="TextBlock">
                <Setter Property="Foreground" Value="#707070"/>
                <Setter Property="FontFamily" Value="Segoe UI Light"/>
                <Setter Property="FontSize" Value="16"/>
            </Style>
            <Style x:Key="H1Style" TargetType="TextBlock">
                <Setter Property="Foreground" Value="#212121"/>
                <Setter Property="FontFamily" Value="Segoe UI Semilight"/>
                <Setter Property="FontSize" Value="26.667"/>
                <Setter Property="Margin" Value="0,0,0,25"/>
            </Style>
            ...
        </ResourceDictionary>
    </Application.Resources>
</Application>

Questo codice XAML dal file MainPage.xaml usa l'estensione di markup {StaticResource} per accedere agli stili TitleStyle e H1Style :

...
<!-- Header -->
<StackPanel x:Name="Header" Grid.Row="0">
    <StackPanel Orientation="Horizontal">
        ...
        <TextBlock Text="Windows SDK Samples" VerticalAlignment="Bottom" Style="{StaticResource TitleStyle}" TextWrapping="Wrap"/>
    </StackPanel>
    <TextBlock x:Name="FeatureName" Text="Add Feature Name" Style="{StaticResource H1Style}" TextWrapping="Wrap"/>
</StackPanel>
 ...

È possibile considerare le risorse nel proprio file XAML usando ResourceDictionary come elemento radice del file. È quindi possibile includere queste risorse in un dizionario risorse FrameworkElement.Resources o Application.Resources . A tale scopo, usare la proprietà ResourceDictionary.MergeDictionary o la proprietà ResourceDictionary.ThemeDictionary dell'elemento ResourceDictionary.

Questo file, Common/Styles1.xaml, definisce le risorse style usando ResourceDictionary come elemento radice:

<ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <Style x:Key="TitleTextStyle" TargetType="TextBlock">
        <Setter Property="FontFamily" Value="Segoe UI Light"/>
        <Setter Property="FontSize" Value="16"/>
    </Style>
    <Style x:Key="HeaderTextStyle" TargetType="TextBlock">
        <Setter Property="FontFamily" Value="Segoe UI Semilight"/>
        <Setter Property="FontSize" Value="26.667"/>
        <Setter Property="Margin" Value="0,0,0,25"/>
    </Style>
    ...
</ResourceDictionary>

Si supponga ora che esista un altro file, Common/Styles2.xaml che definisce in modo analogo le risorse di stile . Questo CODICE XAML illustra come unire le risorse in questi due file usando la proprietà ResourceDictionary.MergeDictionary per creare un dizionario delle risorse Application.Resources . Il codice XAML definisce anche due altre risorse di stile e le unisce con le risorse dei due file.

<Application
    .... >
    <Application.Resources>
        <ResourceDictionary>
            <Style x:Key="ErrorStyle" TargetType="TextBlock">
                <Setter Property="Foreground" Value="DarkRed"/>
                <Setter Property="FontFamily" Value="Segoe UI Semilight"/>
                <Setter Property="FontSize" Value="15"/>
            </Style>
            <Style x:Key="StatusStyle" TargetType="TextBlock">
                <Setter Property="Foreground" Value="Black"/>
                <Setter Property="FontFamily" Value="Segoe UI Semilight"/>
                <Setter Property="FontSize" Value="15"/>
            </Style>
            <ResourceDictionary.MergedDictionaries>
                <!-- 
                    Styles that define common aspects of the platform look and feel
                 -->
                <ResourceDictionary Source="Common/Styles1.xaml"/>
                <ResourceDictionary Source="Common/Styles2.xaml"/>
            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </Application.Resources>
</Application>

Per informazioni sul modo in cui vengono risolte le risorse del dizionario unite, vedere la sezione "Dizionari risorse uniti" di Riferimenti alle risorse ResourceDictionary e XAML.

Proprietà x:Key

In XAML le chiavi per ResourceDictionaryitems vengono dichiarate impostando l'attributo x:Keysugli elementi che rappresentano le risorse XAML. In genere, se si tenta di inserire un elemento figlio che non ha un valore chiave in un ResourceDictionary, viene generata un'eccezione di analisi XAML o un'eccezione di Windows Runtimeexception. La condizione di eccezione può essere nota anche come avviso dalle superfici di progettazione XAML. Tuttavia, esistono tre casi importanti in cui un elemento ResourceDictionarychild non richiederà un valore di attributo x:Key:

Una risorsa Style può usare il valore TargetType come chiave di risorsa implicita. Per altre informazioni sul funzionamento delle chiavi implicite per stili e modelli di controllo, vedere Controlli di stile.
Gli elementi ResourceDictionary con valori di origine che rappresentano i valori ResourceDictionary.MergeDictionary non possono avere un attributo x:Key in ResourceDictionary. All'interno di ogni file di dizionario unito, ovvero quello a cui fa riferimento l'URI come origine, sono necessarie chiavi per ogni risorsa.
L'attributo x:Name può essere usato invece dell'attributo x:Key, per motivi legacy. Tuttavia, l'attributo x:Name non abilita la ricerca della risorsa XAML di tale elemento. La convenzione di identificazione dell'attributo x:Name viene usata per determinati scenari, ad esempio la definizione di animazioni storyboard. Per altre informazioni, vedere attributo x:Name.

Iterazione tramite un resourceDictionary

È possibile eseguire l'iterazione tramite un ResourceDictionary in C# o Microsoft Visual Basic. In molti casi, ad esempio usando la sintassi foreach , il compilatore esegue questo cast per l'utente e non è necessario eseguire il cast IEnumerable in modo esplicito. Se è necessario eseguire il cast in modo esplicito, ad esempio se si vuole chiamare GetEnumerator, eseguire il cast in IEnumerable<T> con un vincolo KeyValuePair<Object,Object> .

ResourceDictionary e Microsoft Visual Studio

Microsoft Visual Studio offre una scelta di pagina Aggiungi nuovo elemento per un dizionario risorse. Usare questa opzione ogni volta che si vuole definire un nuovo dizionario di risorse XAML libero, ad esempio per fungere da origine per un dizionario unito. Microsoft Visual Studio aggiunge anche un dizionario risorse XAML libero al progetto ogni volta che si usa Aggiungi nuovo elemento per creare un controllo modello. Questo dizionario risorse fornisce i modelli di tema predefiniti. Microsoft Visual Studio potrebbe creare un nuovo resourceDictionary per l'utente nel codice XAML se si modificano copie di stili o modelli e un resourceDictionary per la posizione della risorsa scelta (app, pagina o autonoma) non esiste ancora.

Note sulla sintassi XAML

Si noti che la sintassi della raccolta implicita XAML per ResourceDictionary non include un elemento oggetto per ResourceDictionary. Si tratta di un esempio di sintassi di raccolta implicita XAML; un tag che rappresenta l'elemento della raccolta può essere omesso. Gli elementi aggiunti come elementi alla raccolta vengono specificati come elementi figlio di un elemento di proprietà di una proprietà il cui tipo sottostante supporta un metodo Add dizionario/mappa.

Per un dizionario risorse unito, è necessario dichiarare in modo esplicito un elemento oggetto ResourceDictionary, in modo da poter dichiarare anche l'elemento della proprietà ResourceDictionary.MergeDictionary e Source. Pertanto sono presenti almeno due elementi dell'oggetto ResourceDictionary coinvolti e si usa questa sintassi.

<ResourceDictionary>
  <ResourceDictionary.MergedDictionaries>
    <ResourceDictionary Source="uri"/>
    ...
  </ResourceDictionary.MergedDictionaries>
...
</ResourceDictionary>

In questa sintassi l'oggetto ResourceDictionary esterno è resourceDictionary primario. ResourceDictionary interno è l'oggetto ResourceDictionary unito.

Per l'utilizzo della raccolta implicita, viene visualizzato il segnaposto appropriato per la proprietà FrameworkElement.Resources . È anche possibile usare questo utilizzo implicito della raccolta per la proprietà Application.Resources o potenzialmente per una proprietà personalizzata che usa ResourceDictionary come tipo di proprietà.

Tipi condivisibili e tipi UIElement

Un dizionario risorse è una tecnica per definire tipi e valori condivisibili di questi tipi in XAML. Non tutti i tipi o i valori sono adatti per l'utilizzo da resourceDictionary. Esempi di tipi in cui la condivisione è supportata includono Style, qualsiasi sottoclasse FrameworkTemplate , tipi di dati intrinseci XAML, pennelli, colori e trasformazioni. Per altre info sui tipi considerati condivisibili, vedi Riferimenti alle risorse ResourceDictionary e XAML. In genere, i tipi derivati da UIElement non sono condivisibili a meno che non provengano da modelli e applicazione di un modello in un'istanza di controllo specifica. Escludendo il caso del modello, è previsto che un UIElement esista in un'unica posizione in un albero di oggetti dopo la creazione di un'istanza e che un UIElement sia condivisibile potrebbe violare questo principio.

In pratica, la maggior parte delle risorse definite in un ResourceDictionary sarà una delle seguenti:

Modelli di controllo per un controllo, inclusi i relativi stati di visualizzazione.
Stili di supporto per parti di controlli
Stili per gli elementi che fanno parte dell'interfaccia utente tipica dell'app, ma non sono controlli, ad esempio TextBlock
Modelli di dati per controlli e pannelli che usano il data binding
Valori specifici di Brush , principalmente SolidColorBrush
Stringhe o altre costanti che non devono mai essere localizzate (stringhe e costanti che devono essere localizzate non devono essere localizzate in resourceDictionary. Per altre informazioni, vedere Guida introduttiva: Traduzione delle risorse dell'interfaccia utente)

Accesso a un oggetto ResourceDictionary nel codice

L'API usata dal codice per accedere alle risorse in un ResourceDictionary dipende dal linguaggio di programmazione usato:

Per C# o Microsoft Visual Basic si usa l'API che implementa IDictionary<TKey,TValue> e IEnumerable<T>. Ad esempio, TryGetValue o l'indicizzatore Item .
Per le estensioni del componente Visual C++ (C++/CX) si usa l'API che implementa IMap<K,V> e IIterable. Ad esempio, Ricerca.
Le API che non fanno parte del supporto della raccolta, ad esempio Source, sono le stesse in tutte le lingue.

Per altre info su come usare ResourceDictionary nel codice, vedi la sezione "Using a ResourceDictionary from code" (Uso di un resourceDictionary dal codice) di ResourceDictionary e riferimenti alle risorse XAML.

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. Questi 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.

Note per le versioni precedenti

Ottimizzazione del caricamento delle risorse in Windows 8.1

A partire da Windows 8.1, è disponibile un'ottimizzazione del caricamento delle risorse abilitata dal modello di app e dal parser XAML Windows Runtime. Per Windows 8, il parser XAML ha caricato le risorse da app.xaml e le ha create come oggetti come parte dell'avvio. Non era molto efficiente se ci fossero grandi dizionari lì. Inoltre, tali risorse includevano gli elementi necessari per tutti e tre i temi e due dei tre temi non sarebbero nemmeno attivi. A partire da Windows 8.1, il parser XAML crea solo le risorse quando vengono richieste in modo specifico. La richiesta può provenire da altre risorse o dal codice XAML dell'app o della pagina durante il caricamento. Questo comportamento del parser riduce al minimo il tempo necessario per leggere il dizionario a livello di app al momento dell'avvio e consente alla prima pagina dell'app di caricare più velocemente nella maggior parte dei casi. Le risorse necessarie per altri temi attualmente inattivi vengono caricate solo se il tema viene scelto per diventare il tema attivo dall'utente. In quel momento, qualsiasi risorsa in cui è stata usata l'estensione di markup {ThemeResource} per la richiesta viene ricalcolata in base al tema appena attivo.

Comportamento di Windows 8

Windows 8 non sono state descritte le ottimizzazioni descritte in precedenza. ResourceDictionary per Application.Resources doveva completare l'analisi prima che qualsiasi pagina diversa dalla schermata iniziale potesse essere caricata nella finestra dell'app. Per questo motivo è possibile che vengano visualizzate alcune differenze nella tempistica durante la ridefinizione della destinazione dell'app per Windows 8.1. L'app dovrebbe essere caricata più velocemente, ma potrebbe non essere possibile isolare questo miglioramento rispetto ad altre modifiche apportate al codice dell'app come parte del retargeting. Alcune delle posizioni in cui potrebbero verificarsi modifiche di intervallo dovute al caricamento ottimizzato delle risorse includono quando i costruttori vengono chiamati dal parser, per oggetti come oggetti Application , convertitori o altre classi personalizzate. Le app create per Windows 8 che vengono eseguite in Windows 8.1 continuano a usare il comportamento di Windows 8.

Per altre info sulle prestazioni e sul factoring delle risorse XAML, vedi Ottimizzare il markup XAML.

Costruttori

ResourceDictionary()

Inizializza una nuova istanza della classe ResourceDictionary .

Proprietà

Dispatcher	Ottiene CoreDispatcher associato a questo oggetto. CoreDispatcher rappresenta una struttura che può accedere a DependencyObject nel thread dell'interfaccia utente anche se il codice viene avviato da un thread non interfaccia utente. (Ereditato da DependencyObject)
MergedDictionaries	Ottiene una raccolta dei dizionari ResourceDictionary che costituiscono i vari dizionari di risorse nei dizionari uniti.
Size	Ottiene il numero di elementi contenuti nella raccolta.
Source	Ottiene o imposta un URI (Uniform Resource Identifier) che fornisce il percorso di origine di un dizionario risorse unito.
ThemeDictionaries	Ottiene una raccolta di dizionari di risorse uniti che sono specificamente chiave e composti per affrontare gli scenari del tema, ad esempio specificando i valori del tema per "HighContrast".

Metodi

Clear()	Rimuove tutti gli elementi da questo ResourceDictionary.
ClearValue(DependencyProperty)	Cancella il valore locale di una proprietà di dipendenza. (Ereditato da DependencyObject)
First()	Restituisce un iteratore per gli elementi della raccolta.
GetAnimationBaseValue(DependencyProperty)	Restituisce qualsiasi valore di base stabilito per una proprietà di dipendenza, che si applica nei casi in cui un'animazione non è attiva. (Ereditato da DependencyObject)
GetValue(DependencyProperty)	Restituisce il valore effettivo corrente di una proprietà di dipendenza da un oggetto DependencyObject. (Ereditato da DependencyObject)
GetView()	Recupera una visualizzazione rispetto a ResourceDictionary.
HasKey(Object)	Restituisce se resourceDictionary ha una voce con la chiave richiesta.
Insert(Object, Object)	Aggiunge una nuova voce all'oggetto ResourceDictionary.
Lookup(Object)	Restituisce il valore dalla chiave richiesta, se esiste una voce con tale chiave.
ReadLocalValue(DependencyProperty)	Restituisce il valore locale di una proprietà di dipendenza, se viene impostato un valore locale. (Ereditato da DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	Registra una funzione di notifica per l'ascolto delle modifiche a un'istanza di DependencyObject specifica. (Ereditato da DependencyObject)
Remove(Object)	Rimuove un elemento specifico da ResourceDictionary.
SetValue(DependencyProperty, Object)	Imposta il valore locale di una proprietà di dipendenza in un oggetto DependencyObject. (Ereditato da DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	Annulla una notifica di modifica registrata in precedenza chiamando RegisterPropertyChangedCallback. (Ereditato da DependencyObject)

Si applica a