ResourceDictionary Klasse

Definition

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

Vererbung

Object IInspectable DependencyObject ResourceDictionary

Abgeleitet

Microsoft.UI.Xaml.ColorPaletteResources

Microsoft.UI.Xaml.Controls.XamlControlsResources

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

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}-Markuperweiterung 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 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 der beiden Eigenschaften FrameworkElement.Resources und Application.Resources verwendet, die für die Gesamtstruktur einer Windows App SDK-App wichtig sind. XAML-Dateien, die Sie aus einer Startprojektvorlage für eine App abrufen, beginnen mit anfänglichen Werten für FrameworkElement.Resources, und die Datei app.xaml beginnt möglicherweise mit 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 Eigenschaftselement ist kein ResourceDictionary Element untergeordnet, sein Vorhandensein ist jedoch impliziert. Weitere Informationen finden Sie im Abschnitt "Hinweise zur Page.Resources XAML-Syntax" weiter unten. Der XAML-Code platziert einen Style mit dem ResourceDictionaryx:Key-Attributwert "TextBlockStyle1". Weiter unten im XAML verweist die {StaticResource}-Markuperweiterung auf das Style im Ressourcenverzeichnis, um einen Wert für die Style-Eigenschaft des TextBlock-Elements bereitzustellen.

Die Formatvorlage wie gezeigt wendet keine Formatierung auf textBlock an, Sie können jedoch Eigenschaften in Microsoft Visual Studio hinzufügen Style . Sie können die Style Ressource dann beliebig oft auf der Seite verwenden, um Die Einheitlichkeit zu erzwingen.

<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 {StaticResource}-Markuperweiterung , um auf die Stile 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. Dazu verwenden Sie die ResourceDictionary.MergedDictionaries-Eigenschaft oder die ResourceDictionary.ThemeDictionaries-Eigenschaft des ResourceDictionary-Elements.

Diese Datei, Common/Styles1.xaml, definiert Style-Ressourcen mithilfe ResourceDictionary des Stammelements:

<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 auf ähnliche Weise Style-Ressourcen definiert. Dieser XAML-Code zeigt, wie Sie die Ressourcen in diesen beiden Dateien mithilfe der ResourceDictionary.MergedDictionaries-Eigenschaft zusammenführen, um ein Application.Resources-Ressourcenwörterbuch zu erstellen. Der 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 zum Auflösen zusammengeführter Wörterbuchressourcen 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 ResourceDictionary Elemente deklariert, indem das x:Key-Attributauf Elemente festgelegt wird, die die XAML-Ressourcen darstellen. Wenn Sie in der Regel versuchen, ein untergeordnetes Element ohne Schlüsselwert in ein ResourceDictionaryzu setzen, löst dies eine XAML-Analyseausnahme oder eine Windows-Runtime Ausnahme aus. Die Ausnahmebedingung kann auch von XAML-Entwurfsoberflächen als Warnung gekennzeichnet werden. Es gibt jedoch drei bemerkenswerte Fälle, in denen ein ResourceDictionary untergeordnetes Element keinen x:Key-Attributwert erfordert:

• 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 für aufweisen ResourceDictionary. In jeder zusammengeführten Wörterbuchdatei (die vom URI als Quelle referenziert wird) benötigen Sie Schlüssel für jede Ressource.
• Das x:Name-Attribut kann aus Legacygründen anstelle des x:Key-Attributs verwendet werden. Das x:Name-Attribut an sich 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# durchlaufen. In vielen Fällen, z. B. mithilfe von 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, wandeln Sie mit einer Einschränkung in IEnumerable um KeyValuePair<Object,Object> .

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 immer dann, 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 zum Erstellen eines vorlagenbasierten Steuerelements neues Element hinzufügen verwenden. Dieses Ressourcenwörterbuch stellt die Standarddesignvorlagen bereit. Microsoft Visual Studio erstellt möglicherweise eine neue 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 implizite XAML-Auflistungssyntax für ResourceDictionary kein Objektelement für enthält ResourceDictionary. Dies ist ein Beispiel für die syntax der impliziten XAML-Auflistung. ein Tag, der 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 eine Dictionary/map Add-Methode 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 der äußere ResourceDictionary der primäre ResourceDictionary. Das Innere ResourceDictionary ist das ResourceDictionary verschmolzene.

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 als Eigenschaftentyp verwendet ResourceDictionary wird.

Freigegebene Typen und UIElement-Typen

Ein Ressourcenwörterbuch ist ein Verfahren zum Definieren freigegebener Typen und Werte dieser Typen in XAML. Nicht alle Typen oder Werte sind für die Verwendung aus einem ResourceDictionarygeeignet. 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. Im Allgemeinen können uiElement-abgeleitete Typen 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 Stilen 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# verwenden Sie die API, die IDictionary<TKey, TValue> und IEnumerable implementiert. Beispiel: TryGetValue oder item indexer.
• APIs, die nicht Teil der Sammlungsunterstützung sind, wie Source, sind in allen Sprachen identisch.

Weitere Informationen zur Verwendung ResourceDictionary im Code finden Sie im Abschnitt "Verwenden eines ResourceDictionary aus Code" unter 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.

Konstruktoren

Eigenschaften

Methoden

Gilt für:

Weitere Informationen

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