ResourceDictionary Classe

Definizione

/// [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

Requisiti	Descrizione
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 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 il codice, ma questo è meno comune. Puoi usare le risorse per imporre che determinati valori, ad esempio i colori del pennello o le misurazioni dei pixel, vengano usati in modo coerente in tutta l'app. Per altre info sull'uso efficace dei dizionari risorse, vedi Riferimenti alle risorse ResourceDictionary e XAML.

Usi 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 ottieni 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 i valori iniziali per Application.Resources. Le risorse definite dipendono dal modello di avvio del progetto in uso.

Questo codice XAML mostra l'uso di una proprietà FrameworkElement.Resources . In questo caso FrameworkElement è una pagina. Non esiste alcun elemento ResourceDictionary subordinato all'elemento della proprietà Page.Resources, ma la sua presenza è implicita; Per altre info, vedi la sezione "Note sulla sintassi XAML" di seguito. Il codice XAML inserisce uno stile nell'oggetto ResourceDictionary con un valore dell'attributo x:Key "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 visualizzato non applica effettivamente alcun stile al controllo TextBlock, ma è possibile aggiungere proprietà Style in Microsoft Visual Studio. È quindi possibile usare la risorsa Stile con la stessa frequenza desiderata nella pagina per applicare l'uniformità.

È possibile usare Microsoft Visual Studio per creare dizionari risorse. Questo esempio è stato creato con questi passaggi: inserire un controllo 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 . Il codice 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>
 ...

Puoi inserire le risorse nel proprio file XAML usando ResourceDictionary come elemento radice del file. È quindi possibile includere tali risorse in un dizionario risorse FrameworkElement.Resources o Application.Resources . A tale scopo, utilizzare la proprietà ResourceDictionary.MergedDictionaries o la proprietà ResourceDictionary.ThemeDictionaries 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 sia presente un altro file, Common/Styles2.xaml che definisce in modo analogo le risorse di stile . Questo codice XAML mostra come unire le risorse in questi due file usando la proprietà ResourceDictionary.MergedDictionaries per creare un dizionario risorse Application.Resources . Il codice XAML definisce anche due altre risorse style 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 su come vengono risolte le risorse del dizionario unite, vedi la sezione "Dizionari risorse uniti" dei 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 di chiave in un Oggetto ResourceDictionary, viene generata un'eccezione di analisi XAML o un'eccezione di runtime di Windows. La condizione di eccezione può anche essere annotata come avviso dalle superfici di progettazione XAML. Tuttavia, esistono tre casi rilevanti in cui un elemento ResourceDictionarychild non richiede un valore di attributo x:Key:

• Una risorsa Style può usare il valore TargetType come chiave di risorsa implicita. Per altre info sul funzionamento delle chiavi implicite per gli stili e i modelli di controllo, vedi Applicazione di stili ai controlli.
• Gli elementi ResourceDictionary con valori Source che rappresentano i valori ResourceDictionary.MergedDictionaries non possono avere un attributo x:Key in ResourceDictionary. All'interno di ogni file di dizionario unito( 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 con storyboard. Per altre info, vedi attributo x:Name.

Iterazione in un oggetto ResourceDictionary

È possibile scorrere un oggetto 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 in IEnumerable modo esplicito. Se è necessario eseguire il cast in modo esplicito, ad esempio se si vuole chiamare GetEnumerator, eseguire il cast a IEnumerable<T> con un oggetto KeyValuePair<, vincolo Object> .

ResourceDictionary e Microsoft Visual Studio

Microsoft Visual Studio fornisce una scelta di pagina Aggiungi nuovo elemento per un dizionario risorse. Usa questa opzione ogni volta che vuoi definire un nuovo dizionario 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 usi Aggiungi nuovo elemento per creare un controllo basato su modelli. Questo dizionario risorse fornisce i modelli di tema predefiniti. Microsoft Visual Studio potrebbe creare un nuovo ResourceDictionary nel codice XAML se modifichi copie di stili o modelli e un ResourceDictionary per il percorso di risorsa scelto (app, pagina o autonomo) 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. Questo è un esempio di sintassi di raccolta implicita XAML; È possibile omettere un tag che rappresenta l'elemento della raccolta. Gli elementi aggiunti come elementi alla raccolta vengono specificati come elementi figlio di un elemento proprietà di una proprietà il cui tipo sottostante supporta un metodo Dictionary/Map Add .

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

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

In questa sintassi l'oggetto ResourceDictionary esterno è il ResourceDictionary primario. L'oggetto ResourceDictionary interno è l'oggetto ResourceDictionary da unire.

Per l'utilizzo implicito della raccolta, viene visualizzato il segnaposto appropriato per la proprietà FrameworkElement.Resources . È anche possibile utilizzare questa raccolta implicita 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 condivisibili e valori di questi tipi in XAML. Non tutti i tipi o i valori sono adatti per l'utilizzo da un oggetto 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 applicazioni di un modello in un'istanza di controllo specifica. Escludendo il caso del modello, è previsto che un UIElement esista in una sola posizione in un albero di oggetti dopo che è stata creata un'istanza e che un UIElement possa essere condiviso 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 Avvio rapido: 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<T>. Ad esempio, Ricerca.
• Le API che non fanno parte del supporto della raccolta, ad esempio Source, sono uguali 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) dei riferimenti alle risorse ResourceDictionary e XAML.

Risorse di sistema

Alcune risorse del tema fanno riferimento ai valori delle risorse di sistema come sottovalore sottostante. Una risorsa di sistema è un valore di risorsa speciale che non viene trovato in alcun dizionario risorse XAML. Questi valori si basano sul comportamento del supporto XAML di Windows Runtime per inoltrare i valori dal sistema stesso e rappresentarli in un formato a cui può fare riferimento 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, queste 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 potrebbe 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 in fase di avvio e consente alla prima pagina dell'app di caricarsi 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.

Windows 8 comportamento

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 possa essere caricata nella finestra dell'app. A causa di questo potresti vedere alcune differenze di tempo durante la ridefinizione 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 della ridestinazione. Alcune delle posizioni in cui è possibile vedere l'evidenza delle 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 compilate per Windows 8 ma in esecuzione 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.

Vedi anche

• Riferimenti a ResourceDictionary e risorse XAML
• Risorse dell'applicazione ed esempio di localizzazione
• Estensione di markup {ThemeResource}
• Estensione di markup {StaticResource}
• Attributo x:Key