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 Markuperweiterung {StaticResource} und der Markuperweiterung {ThemeResource} 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 Windows App SDK-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 sein Vorhandensein impliziert ist. Weitere Informationen finden Sie im Abschnitt "Hinweise zur XAML-Syntax" weiter unten. Der XAML-Code platziert eine Formatvorlage mit ResourceDictionary einem x:Key-Attributwert von "TextBlockStyle1". Weiter unten im XAML verweist die {StaticResource}-Markuperweiterung auf das Style 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 Eigenschaften in Microsoft Visual Studio hinzufügenStyle. Anschließend können Sie die Style Ressource so oft wie auf der Seite verwenden, um die Uniformität 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 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 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 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 ResourceDictionary Elemente 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 einen ResourceDictionaryzu platzieren, löst dies eine XAML-Analyseausnahme oder eine Windows-Runtime Ausnahme 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 ResourceDictionary untergeordnetes Element kein x:Key-Attributwert erforderlich 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 Source-Werten, die ResourceDictionary.MergedDictionaries-Werte darstellen, können kein x:Key-Attribut enthalten.ResourceDictionary 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 eine ResourceDictionary In C#-Datei durchlaufen. In vielen Fällen, z. B. die Verwendung von foreach Syntax, 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, wandeln Sie mit einer KeyValuePair<Object,Object> Einschränkung in "IEnumerable<T>" um.

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 Ihrem XAML-Code erstellen, wenn Sie Kopien von Formatvorlagen oder Vorlagen bearbeiten und eine ResourceDictionary für den ausgewählten Ressourcenspeicherort (App, Seite oder eigenständige Datei) noch nicht vorhanden ist.

Hinweise zur XAML-Syntax

Beachten Sie, dass die implizite XAML-Auflistungssyntax ResourceDictionary kein Objektelement für die ResourceDictionary. 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 die primäre ResourceDictionary. Das Innere ResourceDictionary wird ResourceDictionary zusammengeführt.

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

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 einer 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 wird die überwiegende Mehrheit der in einer ResourceDictionary Definition definierten Ressourcen eine der folgenden sein:

• 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# verwenden Sie DIE API, die IDictionary<TKey, TValue> und IEnumerable<T> implementiert. Beispiel: TryGetValue oder der Item-Indexer .
• API, die nicht Teil der Sammlungsunterstützung sind, z. B. Source, sind in allen Sprachen identisch.

Weitere Informationen zur Verwendung 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.

Weitere Informationen

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