Freigeben über

ResourceDictionary Klasse

  • Referenz

Definition

Namespace:
Windows.UI.Xaml
Bearbeiten

Definiert 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 abrufen, indem Sie die {StaticResource}-Markuperweiterung und {ThemeResource}-Markuperweiterungen verwenden. Sie können auch mit Code auf Ressourcen zugreifen, dies ist jedoch weniger üblich.

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

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

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:

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

ResourceDictionary()

Initialisiert eine neue instance der ResourceDictionary-Klasse.

Eigenschaften

Dispatcher

Ruft den CoreDispatcher ab, dem dieses Objekt zugeordnet ist. CoreDispatcher stellt eine Funktion dar, die auf das DependencyObject im UI-Thread zugreifen kann, auch wenn der Code von einem Nicht-UI-Thread initiiert wird.

(Geerbt von DependencyObject)
MergedDictionaries

Ruft eine Auflistung der ResourceDictionary-Wörterbücher ab, die die verschiedenen Ressourcenwörterbücher in den zusammengeführten Wörterbüchern bilden.
Size

Ruft die Anzahl der Elemente in der Auflistung ab.
Source

Ruft einen URI (Uniform Resource Identifier) ab, der den Quellspeicherort eines zusammengeführten Ressourcenwörterbuchs angibt, oder legt diesen fest.
ThemeDictionaries

Ruft eine Auflistung von zusammengeführten Ressourcenwörterbüchern ab, die speziell für Designszenarien mit Schlüsseln versehen und zusammengesetzt sind, z. B. durch Bereitstellen von Designwerten für "HighContrast".

Methoden

Clear()

Entfernt alle Elemente aus diesem ResourceDictionary.
ClearValue(DependencyProperty)

Löscht den lokalen Wert einer Abhängigkeitseigenschaft.

(Geerbt von DependencyObject)
First()

Gibt einen Iterator für die Elemente in der Auflistung zurück.
GetAnimationBaseValue(DependencyProperty)

Gibt einen beliebigen Basiswert zurück, der für eine Abhängigkeitseigenschaft eingerichtet wurde, der in Fällen gilt, in denen eine Animation nicht aktiv ist.

(Geerbt von DependencyObject)
GetValue(DependencyProperty)

Gibt den aktuellen effektiven Wert einer Abhängigkeitseigenschaft aus einem DependencyObject zurück.

(Geerbt von DependencyObject)
GetView()

Ruft eine Ansicht für resourceDictionary ab.
HasKey(Object)

Gibt zurück, ob ResourceDictionary über einen Eintrag mit dem angeforderten Schlüssel verfügt.
Insert(Object, Object)

Fügt resourceDictionary einen neuen Eintrag hinzu.
Lookup(Object)

Gibt den Wert aus dem angeforderten Schlüssel zurück, wenn ein Eintrag mit diesem Schlüssel vorhanden ist.
ReadLocalValue(DependencyProperty)

Gibt den lokalen Wert einer Abhängigkeitseigenschaft zurück, wenn ein lokaler Wert festgelegt ist.

(Geerbt von DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)

Registriert eine Benachrichtigungsfunktion zum Lauschen auf Änderungen an einer bestimmten DependencyProperty für dieses DependencyObject-instance.

(Geerbt von DependencyObject)
Remove(Object)

Entfernt ein bestimmtes Element aus resourceDictionary.
SetValue(DependencyProperty, Object)

Legt den lokalen Wert einer Abhängigkeitseigenschaft für ein DependencyObject fest.

(Geerbt von DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)

Bricht eine Änderungsbenachrichtigung ab, die zuvor durch Aufrufen von RegisterPropertyChangedCallback registriert wurde.

(Geerbt von DependencyObject)

Gilt für:

Weitere Informationen