ResourceDictionary Classe

Riferimento

Definizione

Spazio dei nomi:: Microsoft.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 stili, usati dall'app. È possibile definire le risorse in XAML e recuperarle in XAML usando l'estensione di markup {StaticResource} e l'estensione di markup {ThemeResource}. È anche possibile accedere alle risorse con il codice, ma è meno comune.

/// [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 stili, che l'app usa. È possibile definire le risorse in XAML e recuperarle in XAML usando l'estensione di markup {StaticResource} e l'estensione di markup {ThemeResource}. È 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 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 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 ResourceDictionary elemento subordinato all'elemento Page.Resources della proprietà, ma la sua presenza è implicita. Per altre informazioni, vedere la sezione "Note sulla sintassi XAML". XAML inserisce uno stile nell'oggetto ResourceDictionary con un valore di attributo x:Key di "TextBlockStyle1". Più avanti in XAML, l'estensione di markup {StaticResource} fa riferimento all'oggetto Style 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 Style proprietà in Microsoft Visual Studio. È quindi possibile usare la Style risorsa come si vuole 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 . 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 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 chiave in un ResourceDictionaryoggetto , viene generata un'eccezione di analisi XAML o un'eccezione Windows Runtime. La condizione di eccezione può essere nota anche come avviso dalle superfici di progettazione XAML. Tuttavia, esistono tre casi importanti in cui un elemento figlio non richiederà un ResourceDictionary 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 ResourceDictionary elementi con valori di origine che rappresentano i valori ResourceDictionary.MergeDictionary non possono avere un attributo x:Key su 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 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 IEnumerable in modo esplicito. Se è necessario eseguire il cast in modo esplicito, ad esempio se si vuole chiamare GetEnumerator, eseguire il cast in IEnumerable con un KeyValuePair<Object,Object> vincolo.

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 oggetto nel codice XAML se si modificano copie di stili o modelli e un ResourceDictionary oggetto per il percorso delle risorse 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 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 ResourceDictionary elemento oggetto, in modo che sia anche possibile dichiarare l'elemento della proprietà ResourceDictionary.MergeDictionary e Source. Pertanto sono presenti almeno due ResourceDictionary elementi oggetto coinvolti e si usa questa sintassi.

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

In questa sintassi l'esterno ResourceDictionary è l'oggetto primario ResourceDictionary. L'interno ResourceDictionary è l'unione ResourceDictionary .

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 un ResourceDictionaryoggetto . Esempi di tipi in cui la condivisione è supportata includono Style, qualsiasi sottoclasse FrameworkTemplate , tipi di dati intrinseci XAML, pennelli, colori e trasformazioni. Per altre informazioni su quali tipi sono considerati condivisibili, vedere Riferimenti alle risorse ResourceDictionary e XAML. In genere, i tipi derivati da UIElement non sono condivisibili a meno che non provengono da modelli e applicazione di un modello in un'istanza di controllo specifica. Escluso il caso del modello, è previsto che un UIElement esista in un solo posto in un albero di oggetti dopo che viene creata un'istanza e che un UIElement sia condivisibile potrebbe violare potenzialmente questo principio.

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

Modelli di controllo per un controllo, inclusi i relativi stati visivi.
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 data binding
Valori di pennello specifici, principalmente SolidColorBrush
Stringhe o altre costanti che non devono mai essere localizzate (stringhe e costanti che devono essere localizzate non devono essere localizzate in un 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. Ad esempio , TryGetValue o l'indicizzatore Item .
L'API che non fa parte del supporto della raccolta, ad esempio Source, è uguale in tutte le lingue.

Per altre informazioni su come usare ResourceDictionary nel codice, vedere la sezione "Uso di una risorsaDictionary dal codice" di riferimenti alle risorse ResourceDictionary e 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.

Costruttori

ResourceDictionary()

Inizializza una nuova istanza della classe ResourceDictionary .

Proprietà

Dispatcher	Restituisce `null` sempre in un'app SDK per app di Windows. Usare invece DispatcherQueue . (Ereditato da DependencyObject)
DispatcherQueue	Ottiene l'oggetto `DispatcherQueue` associato. Rappresenta `DispatcherQueue` una struttura che può accedere al thread dell'interfaccia utente anche se il codice viene avviato da un thread non dell'interfaccia `DependencyObject` 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