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

Hinweise

Ein Ressourcenwörterbuch ist ein Repository für XAML-Ressourcen, z. B. Stile, die von Ihrer App verwendet werden. Sie definieren die Ressourcen in XAML und können sie dann in XAML mithilfe der {StaticResource}-Markuperweiterung und {ThemeResource}-Markuperweiterungen abrufen. Sie können auch mit Code auf Ressourcen zugreifen, dies ist jedoch weniger üblich. Sie können Ressourcen verwenden, um zu erzwingen, dass bestimmte Werte wie Pinselfarben oder Pixelmessungen konsistent in Ihrer App 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 der beiden Eigenschaften FrameworkElement.Resources und Application.Resources verwendet, die für die Gesamtstruktur einer UWP-App wichtig sind. XAML-Dateien, die Sie aus einer Startprojektvorlage für eine App abrufen, beginnen mit den Anfangswerten für FrameworkElement.Resources, und die Datei app.xaml beginnt möglicherweise mit den Anfangswerten für Application.Resources. Welche Ressourcen genau dort definiert sind, hängt davon ab, welche Projektstartvorlage Sie verwenden.

Dieser XAML-Code zeigt die Verwendung einer FrameworkElement.Resources-Eigenschaft . In diesem Fall ist das FrameworkElement eine Seite. Dem Page.Resources-Eigenschaftselement ist kein ResourceDictionary-Element untergeordnet, sein Vorhandensein ist jedoch impliziert. weitere Informationen finden Sie weiter unten im Abschnitt "Hinweise zur XAML-Syntax". Der XAML-Code platziert einen Style in ResourceDictionary mit dem x:Key-Attributwert "TextBlockStyle1". Weiter unten im XAML-Code verweist die {StaticResource}-Markuperweiterung auf den Style im Ressourcenverzeichnis, um einen Wert für die Style-Eigenschaft des TextBlock-Elements bereitzustellen.

Die Formatvorlage wendet wie gezeigt keine Formatierung auf textBlock an, Sie können jedoch Formatvorlageneigenschaften in Microsoft Visual Studio hinzufügen. Sie können die Style-Ressource dann beliebig oft auf der Seite verwenden, um 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: Platzieren Sie einen TextBlock auf der Entwurfsoberfläche, klicken Sie mit der rechten Maustaste, wählen Sie Format bearbeiten/Leer erstellen und dann "This document" (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 Ressourcenverzeichnis, 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 {StaticResource}-Markuperweiterung , um auf die Formatvorlagen TitleStyle und H1Style zuzugreifen:

...
<!-- 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 einbeziehen, indem Sie ResourceDictionary als Stammelement der Datei verwenden. Sie können diese Ressourcen dann in ein FrameworkElement.Resources - oder Application.Resources-Ressourcenwörterbuch einschließen. Verwenden Sie dazu die ResourceDictionary.MergedDictionaries-Eigenschaft 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 ähnlich definiert. Dieser XAML-Code zeigt, wie die Ressourcen in diesen beiden Dateien mithilfe der ResourceDictionary.MergedDictionaries-Eigenschaft zusammengeführt werden , um ein Application.Resources-Ressourcenwörterbuch zu erstellen. Das XAML definiert auch 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" unter 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 versuchen, ein untergeordnetes Element, das keinen Schlüsselwert hat, in ein ResourceDictionary-Element einzufügen, wird in der Regel eine XAML-Analyseausnahme oder eine Windows-Runtimeexception ausgelöst. Die Ausnahmebedingung kann auch von XAML-Entwurfsoberflächen als Warnung gekennzeichnet werden. Es gibt jedoch drei wichtige Fälle, in denen ein ResourceDictionarychild-Element keinen x:Key-Attributwerterfordert:

• Eine Style-Ressource kann ihren TargetType-Wert als impliziten Ressourcenschlüssel verwenden. Weitere Informationen zur Funktionsweise impliziter Schlüssel für Stile und Steuerelementvorlagen finden Sie unter Formatieren von Steuerelementen.
• Die ResourceDictionary-Elemente mit Source-Werten , die ResourceDictionary.MergedDictionaries-Werte darstellen, können kein x:Key-Attribut auf ResourceDictionary aufweisen. In jeder zusammengeführten Wörterbuchdatei (die, auf die vom 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 allein aktiviert jedoch keine XAML-Ressourcensuche für dieses Element. Die x:Name-Attributidentifikationskonvention wird für bestimmte Szenarien verwendet, z. B. für das Definieren von Storyboardanimationen. 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. mit foreach-Syntax , führt der Compiler diese Umwandlung für Sie durch, und Sie müssen nicht explizit in IEnumerable umwandeln. Wenn Sie eine explizite Umwandlung durchführen müssen, z. B. wenn Sie GetEnumerator aufrufen möchten, wird die Umwandlung in IEnumerable<T> mit einer KeyValuePair-Objekt,Object-Einschränkung<> erfolgen.

ResourceDictionary und Microsoft Visual Studio

Microsoft Visual Studio bietet eine Auswahl auf 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 neues Element hinzufügen verwenden, um ein Steuerelement mit Vorlagen zu erstellen. Dieses Ressourcenwörterbuch stellt die Standarddesignvorlagen bereit. Microsoft Visual Studio erstellt möglicherweise ein neues ResourceDictionary für Sie in Ihrem XAML-Code, 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 Syntax der impliziten XAML-Auflistung für ResourceDictionary kein Objektelement für ResourceDictionary enthält. Dies ist ein Beispiel für die Syntax der impliziten XAML-Auflistung. 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 die Add-Methode dictionary/map unterstützt.

Für ein zusammengeführtes Ressourcenwörterbuch müssen Sie ein ResourceDictionary-Objektelement explizit deklarieren, damit Sie auch das ResourceDictionary.MergedDictionaries-Eigenschaftselement und 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 Sammlungsverwendung auch für die Application.Resources-Eigenschaft oder möglicherweise für eine benutzerdefinierte Eigenschaft verwenden, die ResourceDictionary als Eigenschaftentyp verwendet.

Freigegebene Typen und UIElement-Typen

Ein Ressourcenwörterbuch ist eine Technik zum Definieren freigegebener Typen und Werte dieser Typen in XAML. Nicht alle Typen oder Werte sind für die Verwendung aus einem ResourceDictionary geeignet. Beispiele für Typen, in denen die Freigabe unterstützt wird, sind Style, jede FrameworkTemplate-Unterklasse , die intrinsischen XAML-Datentypen, Pinsel, Farben und Transformationen. Weitere Informationen dazu, welche Typen als freigegeben gelten, finden Sie unter ResourceDictionary- und XAML-Ressourcenverweise. Von UIElement abgeleitete Typen können im Allgemeinen nicht freigegeben werden, es sei denn, sie stammen aus Vorlagen und der Anwendung einer Vorlage auf einem bestimmten Steuerelement instance. Mit Ausnahme des Vorlagenfalls wird erwartet, dass ein UIElement nur an einer Stelle in einer Objektstruktur vorhanden ist, nachdem es instanziiert wurde, und wenn ein UIElement freigegeben werden kann, würde dies möglicherweise gegen dieses Prinzip verstoßen.

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-Benutzeroberfläche sind, aber keine Steuerelemente sind, z. B. TextBlock
• Datenvorlagen für Steuerelemente und Bereiche, 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 die API, die IMap<K,V> und IIterable implementiert. Beispiel : Suchen.
• API, die nicht Teil der Sammlungsunterstützung sind, wie Source, sind in allen Sprachen identisch.

Weitere Informationen zur Verwendung von ResourceDictionary im Code finden Sie im Abschnitt "Verwenden eines ResourceDictionary aus Code" von ResourceDictionary und XAML-Ressourcenverweise.

Systemressourcen

Von einigen Designressourcen wird auf Systemressourcenwerte als zugrunde liegender Unterwert verwiesen. Eine Systemressource ist eine spezieller Ressourcenwert, der in keinem XAML-Ressourcenverzeichnis zu finden ist. Diese Werte sind vom Verhalten in der XAML-Unterstützung der Windows-Runtime abhängig, um Werte aus dem System selbst weiterzuleiten und in einer Form darzustellen, auf die von einer XAML-Ressource verwiesen werden kann.

Hinweise zu früheren Versionen

Optimierung des Ressourcenladens in Windows 8.1

Ab Windows 8.1 gibt es eine Optimierung zum Laden von Ressourcen, die durch das App-Modell und den Windows-Runtime XAML-Parser aktiviert wird. Für Windows 8 hat der XAML-Parser Ressourcen aus "app.xaml" geladen und während des Startvorgangs jeweils als Objekte erstellt. Das war nicht sehr effizient, wenn es dort große Wörterbücher gab. Außerdem enthielten diese Ressourcen die Elemente, die von allen drei Designs benötigt wurden, und zwei der drei Themen waren nicht einmal aktiv. Ab Windows 8.1 erstellt der XAML-Parser die Ressourcen nur, wenn sie speziell angefordert werden. Die Anforderung kann von anderen Ressourcen oder aus App- oder Seiten-XAML stammen, wenn jede geladen wird. Dieses Parserverhalten minimiert die Zeit, die zum Lesen des Wörterbuchs auf App-Ebene zum Startzeit benötigt wird, und ermöglicht es, dass die erste App-Seite in den meisten Fällen schneller geladen wird. 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-Verhaltensweise

Windows 8 nicht über die oben beschriebenen Optimierungen verfügten. Das ResourceDictionary für 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 können Sie einige Unterschiede in der Zeitplanung feststellen, wenn Sie Ihre App für Windows 8.1 erneut abrufen. 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 im Rahmen des Retargetings an Ihrem App-Code vorgenommen haben. Zu den Stellen, an denen möglicherweise Hinweise auf Zeitänderungen aufgrund des optimierten Ladens von Ressourcen angezeigt werden, gehören, wenn die Konstruktoren vom Parser für Objekte wie Application-Objekte , Konverter oder andere benutzerdefinierte Klassen aufgerufen werden. Apps, die für Windows 8 kompiliert wurden, aber unter Windows 8.1 ausgeführt werden, weisen weiterhin das Windows 8-Verhalten auf.

Weitere Informationen zu Leistung und XAML-Ressourcenfaktoring finden Sie unter Optimieren Ihres XAML-Markups.

Konstruktoren

Eigenschaften

Methoden

Gilt für:

Weitere Informationen

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