ResourceDictionary Klasse

Definition

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

Vererbung

Object IInspectable DependencyObject ResourceDictionary

Abgeleitet

Windows.UI.Xaml.ColorPaletteResources

Attribute

ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Implementiert

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

Windows-Anforderungen

Anforderungen	Beschreibung
Gerätefamilie	Windows 10 (eingeführt in 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (eingeführt in v1.0)

Hinweise

Ein Ressourcenwörterbuch ist ein Repository für XAML-Ressourcen, z. B. Stile, die Ihre App verwendet. Sie definieren die Ressourcen in XAML und können sie dann in XAML mithilfe der {StaticResource}-Markuperweiterung und der {ThemeResource}-Markuperweiterungen abrufen. Sie können auch mit Code auf Ressourcen zugreifen, aber das ist weniger häufig. Sie können Ressourcen verwenden, um zu erzwingen, dass bestimmte Werte wie Pinselfarben oder Pixelmaße in der gesamten App konsistent verwendet werden. Weitere Informationen zur effektiven Verwendung von Ressourcenwörterbüchern finden Sie unter ResourceDictionary- und XAML-Ressourcenverweise.

Verwendung von ResourceDictionary-Elementen

Der ResourceDictionary-Typ wird als Wert von zwei Eigenschaften verwendet, "FrameworkElement.Resources " und "Application.Resources", die für die gesamtstruktur einer UWP-App wichtig sind. XAML-Dateien, die Sie von einer Startprojektvorlage für eine App erhalten, beginnen mit den Anfangswerten für "FrameworkElement.Resources", und die Datei "app.xaml" kann mit den Anfangswerten für "Application.Resources" beginnen. Genau welche Ressourcen definiert sind, hängt davon ab, welche Projektstartvorlage Sie verwenden.

Dieser XAML-Code zeigt die Verwendung einer FrameworkElement.Resources-Eigenschaft . In diesem Fall ist " FrameworkElement " eine Seite. Es gibt kein ResourceDictionary-Element, das dem Page.Resources-Eigenschaftselement untergeordnet ist, aber seine Anwesenheit wird impliziert. Weitere Informationen finden Sie im Abschnitt "Hinweise zur XAML-Syntax" weiter unten. Der XAML-Code platziert eine Formatvorlage in das ResourceDictionary mit einem x:Key-Attributwert von "TextBlockStyle1". Weiter unten im XAML verweist die {StaticResource}-Markuperweiterung auf die Formatvorlage im Ressourcenwörterbuch, um einen Wert für die Style-Eigenschaft des TextBlock-Elements bereitzustellen.

Die Formatvorlage wie dargestellt wendet keine Formatierung auf den TextBlock an, Sie können jedoch Formatvorlageneigenschaften in Microsoft Visual Studio hinzufügen. Anschließend können Sie die Style-Ressource so oft wie auf der Seite verwenden, um die Uniformität zu erzwingen.

Sie können Microsoft Visual Studio verwenden, um Ressourcenwörterbücher zu erstellen. Dieses Beispiel wurde mit den folgenden Schritten erstellt: Legen Sie einen TextBlock auf die Entwurfsoberfläche, klicken Sie mit der rechten Maustaste, wählen Sie "Formatvorlage bearbeiten/Leer erstellen" und dann "Dieses Dokument" aus, um die neue Ressource in Page.Resources zu definieren.

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

Dieser XAML-Code aus der Datei "AppPage.xaml" des AtomPub-Beispiels zeigt die Verwendung einer Application.Resources-Eigenschaft . Der XAML-Code platziert zwei Style-Elemente in das Ressourcenwörterbuch, sodass sie in der gesamten Anwendung verfügbar sind.

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

Dieser XAML-Code aus der Datei "MainPage.xaml" verwendet die Markuperweiterung {StaticResource} für den Zugriff auf die Formatvorlagen TitleStyle und 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>
 ...

Sie können Ressourcen in ihre eigene XAML-Datei einteilen, indem Sie ResourceDictionary als Stammelement der Datei verwenden. Sie können diese Ressourcen dann in ein FrameworkElement.Resources - oder Application.Resources-Ressourcenressourcenverzeichnis einschließen. Dazu verwenden Sie die Eigenschaft ResourceDictionary.MergedDictionaries oder die ResourceDictionary.ThemeDictionaries-Eigenschaft des ResourceDictionary-Elements.

Diese Datei , Common/Styles1.xaml, definiert Style-Ressourcen mithilfe von ResourceDictionary als Stammelement:

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

Angenommen, es gibt eine andere Datei, Common/Styles2.xaml, die Style-Ressourcen entsprechend definiert. Dieser XAML-Code zeigt, wie die Ressourcen in diesen beiden Dateien mithilfe der Eigenschaft ResourceDictionary.MergedDictionaries zusammengeführt werden, um ein Application.Resources-Ressourcenverzeichnis zu erstellen. Der XAML-Code definiert außerdem zwei weitere Style-Ressourcen und führt sie mit den Ressourcen aus den beiden Dateien zusammen.

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

Informationen dazu, wie zusammengeführte Wörterbuchressourcen aufgelöst werden, finden Sie im Abschnitt "Zusammengeführte Ressourcenwörterbücher" von ResourceDictionary- und XAML-Ressourcenverweise.

Die x:Key-Eigenschaft

In XAML werden die Schlüssel für ResourceDictionaryitems deklariert, indem das x:Key-Attributfür Elemente festgelegt wird, die die XAML-Ressourcen darstellen. Wenn Sie in der Regel versuchen, ein untergeordnetes Element, das keinen Schlüsselwert enthält, in ein ResourceDictionary zu setzen, löst dies eine XAML-Analyseausnahme oder eine Windows RuntimeException aus. Die Ausnahmebedingung kann auch als Warnung durch XAML-Entwurfsoberflächen angegeben werden. Es gibt jedoch drei wichtige Fälle, in denen für ein ResourceDictionarychild-Element kein x:Key-Attributwerterforderlich ist:

• Eine Style-Ressource kann den TargetType-Wert als impliziten Ressourcenschlüssel verwenden. Weitere Informationen dazu, wie implizite Schlüssel für Stile und Steuerelementvorlagen funktionieren, finden Sie unter Formatieren von Steuerelementen.
• Die ResourceDictionary-Elemente mit Quellwerten , die ResourceDictionary.MergedDictionaries-Werte darstellen, können kein x:Key-Attribut für ResourceDictionary aufweisen. In jeder zusammengeführten Wörterbuchdatei (auf die von URI als Quelle verwiesen wird) benötigen Sie Schlüssel für jede Ressource.
• Das x:Name-Attribut kann aus älteren Gründen anstelle des x:Key-Attributs verwendet werden. Das x:Name-Attribut selbst aktiviert jedoch nicht die XAML-Ressourcensuche dieses Elements. Das x:Name-Attribut zur Identifizierungskonvention wird für bestimmte Szenarien wie das Definieren von Storyboardanimationen verwendet. Weitere Informationen finden Sie unter "x:Name"-Attribut.

Durchlaufen eines ResourceDictionary

Sie können ein ResourceDictionary in C# oder Microsoft Visual Basic durchlaufen. In vielen Fällen, z. B. die Verwendung der Foreachsyntax , führt der Compiler diese Umwandlung für Sie durch, und Sie müssen nicht explizit umwandeln IEnumerable . Wenn Sie z. B. getEnumerator explizit umwandeln möchten, wechseln Sie mit einer KeyValuePair-Objekteinschränkung<> in IEnumerable<T>.

ResourceDictionary und Microsoft Visual Studio

Microsoft Visual Studio bietet eine Auswahl der Seite "Neues Element hinzufügen" für ein Ressourcenwörterbuch. Verwenden Sie diese Option, wenn Sie ein neues loses XAML-Ressourcenwörterbuch definieren möchten, z. B. als Quelle für ein zusammengeführtes Wörterbuch. Microsoft Visual Studio fügt dem Projekt auch ein loses XAML-Ressourcenwörterbuch hinzu, wenn Sie ein vorlagenbasiertes Steuerelement mithilfe von "Neues Element hinzufügen" erstellen. Dieses Ressourcenverzeichnis stellt die Standarddesignvorlagen bereit. Microsoft Visual Studio möglicherweise ein neues ResourceDictionary für Sie in Xaml erstellen, wenn Sie Kopien von Formatvorlagen oder Vorlagen bearbeiten und ein ResourceDictionary für den ausgewählten Ressourcenspeicherort (App, Seite oder eigenständig) noch nicht vorhanden ist.

Hinweise zur XAML-Syntax

Beachten Sie, dass die implizite XAML-Auflistungssyntax für ResourceDictionary kein Objektelement für das ResourceDictionary enthält. Dies ist ein Beispiel für eine implizite XAML-Sammlungssyntax; ein Tag, das das Auflistungselement darstellt, kann weggelassen werden. Die Elemente, die der Auflistung als Elemente hinzugefügt werden, werden als untergeordnete Elemente eines Eigenschaftselements einer Eigenschaft angegeben, deren zugrunde liegender Typ ein Wörterbuch/eine Zuordnungs-Add-Methode unterstützt.

Für ein zusammengeführtes Ressourcenwörterbuch müssen Sie ein ResourceDictionary-Objektelement explizit deklarieren, sodass Sie auch das ResourceDictionary.MergedDictionaries-Eigenschaftselement und die Source deklarieren können. Daher sind mindestens zwei ResourceDictionary-Objektelemente beteiligt, und Sie verwenden diese Syntax.

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

In dieser Syntax ist das äußere ResourceDictionary das primäre ResourceDictionary. Das innere ResourceDictionary ist das ResourceDictionary, das zusammengeführt wird.

Für die implizite Sammlungsverwendung wird der Platzhalter entsprechend der Eigenschaft "FrameworkElement.Resources " angezeigt. Sie können diese implizite Sammlung auch für die Application.Resources-Eigenschaft oder potenziell für eine benutzerdefinierte Eigenschaft verwenden, die ResourceDictionary als Eigenschaftstyp verwendet.

Freigabefähige Typen und UIElement-Typen

Ein Ressourcenwörterbuch ist eine Technik zum Definieren von gemeinsam verwendbaren Typen und Werten dieser Typen in XAML. Nicht alle Typen oder Werte eignen sich für die Verwendung aus einem ResourceDictionary. Beispiele für Typen, bei denen die Freigabe unterstützt wird, sind Style, jede FrameworkTemplate-Unterklasse , die systeminternen XAML-Datentypen, Pinsel, Farben und Transformationen. Weitere Informationen dazu, welche Typen als gemeinsam verwendet werden können, finden Sie unter ResourceDictionary- und XAML-Ressourcenverweise. Im Allgemeinen können uiElement-abgeleitete Typen nicht gemeinsam verwendet werden, es sei denn, sie stammen aus Vorlagen und der Anwendung einer Vorlage auf einer bestimmten Steuerelementinstanz. Ohne den Vorlagenfall wird erwartet, dass ein UIElement nur an einer Stelle in einer Objektstruktur vorhanden ist, nachdem es instanziiert wurde, und wenn ein UIElement gemeinsam verwendet werden kann, würde dieses Prinzip möglicherweise verletzen.

In der Praxis ist die überwiegende Mehrheit der in einem ResourceDictionary definierten Ressourcen eine der folgenden:

• Steuerelementvorlagen für ein Steuerelement, einschließlich seiner visuellen Zustände.
• Unterstützen von Formatvorlagen für Teile von Steuerelementen
• Stile für Elemente, die Teil der typischen App-UI sind, jedoch keine Steuerelemente sind, z. B. TextBlock
• Datenvorlagen für Steuerelemente und Panels, die datenbindung verwenden
• Bestimmte Pinselwerte , hauptsächlich SolidColorBrush
• Zeichenfolgen oder andere Konstanten, die nie lokalisiert werden müssen (Zeichenfolgen und Konstanten, die lokalisiert werden müssen, sollten sich nicht in einem ResourceDictionary befinden; weitere Informationen finden Sie unter Schnellstart: Übersetzen von UI-Ressourcen)

Zugreifen auf ein ResourceDictionary-Objekt im Code

Die API, die Ihr Code für den Zugriff auf die Ressourcen in einem ResourceDictionary verwendet, hängt davon ab, welche Programmiersprache Sie verwenden:

• Für C# oder Microsoft Visual Basic verwenden Sie DIE API, die IDictionary<TKey, TValue> und IEnumerable<T> implementiert. Beispiel: TryGetValue oder der Item-Indexer .
• Für Visual C++-Komponentenerweiterungen (C++/CX) verwenden Sie API, die IMap<K,V> und IIterable<T> implementieren. Beispiel: Nachschlagen.
• API, die nicht Teil der Sammlungsunterstützung sind, z. B. Source, sind in allen Sprachen identisch.

Weitere Informationen zur Verwendung von ResourceDictionary im Code finden Sie im Abschnitt "Using a ResourceDictionary from code" in ResourceDictionary und XAML-Ressourcenverweise.

Systemressourcen

Einige Themenressourcen verweisen auf Systemressourcen-Werte als zugrunde liegende Unterwerte. Eine Systemressource ist ein spezieller Ressourcenwert, der in keinem XAML-Ressourcenwörterbuch gefunden wird. Diese Werte basieren auf dem Verhalten in der WINDOWS-Runtime-XAML-Unterstützung zum Weiterleiten von Werten vom System selbst und stellen sie in einer Form dar, auf die eine XAML-Ressource verweisen kann.

Hinweise für frühere Versionen

Optimierung des Ressourcenladevorgangs in Windows 8.1

Ab Windows 8.1 gibt es eine Optimierung des Ressourcenladevorgangs, die vom App-Modell und dem Windows-Runtime XAML-Parser aktiviert ist. Für Windows 8 hat der XAML-Parser Ressourcen aus "app.xaml" geladen und im Rahmen des Starts als Objekte erstellt. Das war nicht sehr effizient, wenn dort große Wörterbücher vorhanden waren. Außerdem enthielten diese Ressourcen die Elemente, die von allen drei Designs benötigt wurden, und zwei der drei Designs würden nicht einmal aktiv sein. Ab Windows 8.1 erstellt der XAML-Parser nur die Ressourcen, wenn sie speziell angefordert werden. Die Anforderung kann aus anderen Ressourcen oder aus App- oder Seiten-XAML stammen, sobald jedes geladen wird. Dieses Parserverhalten minimiert die Zeit, die zum Lesen des Wörterbuchs auf App-Ebene beim Start benötigt wird, und ermöglicht es der ersten App-Seite, in den meisten Fällen schneller zu laden. Ressourcen, die von anderen derzeit inaktiven Designs benötigt werden, werden nur geladen, wenn dieses Design vom Benutzer als aktives Design ausgewählt wird. Zu diesem Zeitpunkt wird jede Ressource, in der die {ThemeResource}-Markuperweiterung für die Anforderung verwendet wurde, basierend auf dem neu aktiven Design neu berechnet.

Windows 8 Verhalten

Windows 8 haben die oben beschriebenen Optimierungen nicht. Das ResourceDictionary Application.Resources musste die Analyse abschließen, bevor eine andere Seite als der Begrüßungsbildschirm in das Fenster der App geladen werden konnte. Aus diesem Grund sehen Sie möglicherweise einige Unterschiede bei der Anzeigedauer, wenn Sie Ihre App für Windows 8.1 neu zuweisen. Die App sollte schneller geladen werden, es ist jedoch möglicherweise nicht möglich, diese Verbesserung im Vergleich zu anderen Änderungen zu isolieren, die Sie an Ihrem App-Code vorgenommen haben, als Teil des Retargetings. Einige der Stellen, an denen Sie aufgrund optimierter Ressourcenladezeiten möglicherweise Hinweise auf Zeitänderungen sehen können, sind beim Aufrufen der Konstruktoren durch den Parser für Objekte wie Application-Objekte , Konverter oder andere benutzerdefinierte Klassen enthalten. Apps, die für Windows 8 kompiliert wurden, aber auf Windows 8.1 ausgeführt werden, verwenden weiterhin das Windows 8 Verhalten.

Weitere Informationen zu Leistung und XAML-Ressourcenfaktorierung finden Sie unter Optimieren des XAML-Markups.

Siehe auch

• ResourceDictionary- und XAML-Ressourcenreferenzen
• Anwendungsressourcen und Lokalisierungsbeispiel
• {ThemeResource}-Markuperweiterung
• {StaticResource}-Markuperweiterung
• x:Key-Attribut