ResourceDictionary Classe

Definizione

/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 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(Microsoft.UI.Xaml.WinUIContract), 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

Microsoft.UI.Xaml.ColorPaletteResources

Microsoft.UI.Xaml.Controls.XamlControlsResources

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

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 ResourceDictionary tipo viene usato come valore di due proprietà, FrameworkElement.Resources e Application.Resources, importanti per la struttura complessiva di un'app SDK per app di Windows. 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 ResourceDictionary elemento subordinato all'elemento Page.Resources della proprietà, ma la sua presenza è implicita. Per altre info, vedi la sezione "Note sulla sintassi XAML" di seguito. Il codice XAML inserisce un oggetto Style in ResourceDictionary con un valore di attributo x:Key "TextBlockStyle1". Più avanti in XAML, l'estensione di markup {StaticResource} fa riferimento a Style nel dizionario risorse per fornire un valore per la proprietà Style dell'elemento TextBlock .

Lo stile mostrato non applica effettivamente alcun stile al controllo TextBlock, ma è possibile aggiungere Style proprietà in Microsoft Visual Studio. È quindi possibile usare la Style risorsa con la stessa frequenza desiderata nella pagina per applicare l'uniformità.

<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 ResourceDictionary gli elementi 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 ResourceDictionary, viene generata un'eccezione di analisi XAML o un'eccezione Windows Runtime. La condizione di eccezione può anche essere annotata come avviso dalle superfici di progettazione XAML. Tuttavia, esistono tre casi rilevanti in cui un ResourceDictionary elemento figlio 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 ResourceDictionary elementi con valori di origine 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 ResourceDictionary oggetto in C#. In molti casi, ad esempio usando foreach la sintassi, 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 KeyValuePair<Object,Object> vincolo.

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 crearne uno nuovo ResourceDictionary nel codice XAML se stai modificando copie di stili o modelli e un ResourceDictionary oggetto per il percorso della 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 ResourceDictionary elemento oggetto, in modo da poter anche dichiarare l'elemento della proprietà ResourceDictionary.MergedDictionaries e Source. Pertanto, sono coinvolti almeno due ResourceDictionary elementi oggetto e si usa questa sintassi.

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

In questa sintassi l'esterno ResourceDictionary è il primario ResourceDictionary. L'interno ResourceDictionary è 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# si usa l'API che implementa IDictionary<TKey,TValue> e IEnumerable<T>. Ad esempio, TryGetValue o l'indicizzatore Item .
• 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) di 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.

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