Freigeben über

ResourceDictionary- und XAML-Ressourcenreferenzen

Sie können die Benutzeroberfläche oder Ressourcen für Ihre App mithilfe von XAML definieren. Ressourcen sind in der Regel Definitionen einiger Objekte, die Sie mehr als einmal verwenden möchten. Um später auf eine XAML-Ressource zu verweisen, geben Sie einen Schlüssel für eine Ressource an, der wie ihr Name fungiert. Sie können auf eine Ressource innerhalb einer App oder von einer beliebigen XAML-Seite darauf verweisen. Sie können Ihre Ressourcen mithilfe eines ResourceDictionary-Elements aus dem Windows-Runtime-XAML-Code definieren. Anschließend können Sie mithilfe einer StaticResource-Markuperweiterung oder ThemeResource-MarkuperweiterungIhre Ressourcen referenzieren.

Die XAML-Elemente, die Sie am häufigsten deklarieren möchten, da XAML-Ressourcen Stil, ControlTemplate, Animationskomponenten und Brush-Unterklassen enthalten. Hier erklären wir, wie Sie ein ResourceDictionary und Schlüsselressourcen definieren und wie XAML-Ressourcen sich auf andere Ressourcen beziehen, die Sie als Teil Ihrer App oder Ihres App-Pakets definieren. Darüber hinaus erläutern wir erweiterte Funktionen des Ressourcenwörterbuchs, wie zum Beispiel MergedDictionaries und ThemeDictionaries.

Voraussetzungen

Ein solides Verständnis des XAML-Markups. Es wird empfohlen, die XAML-Übersichtzu lesen.

Definieren und Verwenden von XAML-Ressourcen

XAML-Ressourcen sind Objekte, auf die aus Markup mehr als einmal verwiesen wird. Ressourcen werden in einem ResourceDictionary-definiert, in der Regel in einer separaten Datei oder oben auf der Markupseite, wie hier dargestellt.

<Page
    x:Class="MSDNSample.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <Page.Resources>
        <x:String x:Key="greeting">Hello world</x:String>
        <x:String x:Key="goodbye">Goodbye world</x:String>
    </Page.Resources>

    <TextBlock Text="{StaticResource greeting}" Foreground="Gray" VerticalAlignment="Center"/>
</Page>

In diesem Beispiel:

  • <Page.Resources>…</Page.Resources> – Definiert das Ressourcenwörterbuch.
  • <x:String> – Definiert die Ressource mit dem Schlüssel "greeting".
  • {StaticResource greeting} – Sucht die Ressource mit dem Schlüssel "greeting", die der Eigenschaft Text des TextBlockzugewiesen ist.

Hinweis Verwechseln Sie die Konzepte im Zusammenhang mit ResourceDictionary nicht mit der Buildaktion Resource, mit Ressourcendateien (.resw) oder mit anderen "Ressourcen", die im Kontext der Strukturierung des Codeprojekts erläutert werden, das Ihr App-Paket erzeugt.

Ressourcen müssen keine Zeichenfolgen sein. sie können ein beliebiges gemeinsam nutzbares Objekt sein, z. B. Stile, Vorlagen, Pinsel und Farben. Steuerelemente, Shapes und andere FrameworkElement-können jedoch nicht geteilt werden, sodass sie nicht als wiederverwendbare Ressourcen deklariert werden können. Weitere Informationen zur Freigabe finden Sie in den XAML-Ressourcen, die später in diesem Thema Abschnitt gemeinsam verwendet werden können müssen.

Hier werden sowohl ein Pinsel als auch eine Zeichenfolge als Ressourcen deklariert und von Steuerelementen auf einer Seite verwendet.

<Page
    x:Class="SpiderMSDN.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <Page.Resources>
        <SolidColorBrush x:Key="myFavoriteColor" Color="green"/>
        <x:String x:Key="greeting">Hello world</x:String>
    </Page.Resources>

    <TextBlock Foreground="{StaticResource myFavoriteColor}" Text="{StaticResource greeting}" VerticalAlignment="Top"/>
    <Button Foreground="{StaticResource myFavoriteColor}" Content="{StaticResource greeting}" VerticalAlignment="Center"/>
</Page>

Alle Ressourcen müssen über einen Schlüssel verfügen. In der Regel handelt es sich bei diesem Schlüssel um einen mit x:Key="myString" definierten String. Es gibt jedoch einige andere Möglichkeiten zum Angeben eines Schlüssels:

  • Style und ControlTemplate benötigen einen TargetTypeund werden den TargetType als Schlüssel verwenden, wenn x:Key nicht angegeben ist. In diesem Fall ist der Schlüssel das tatsächliche Type-Objekt, keine Zeichenfolge. (Siehe Beispiele unten)
  • DataTemplate- Ressourcen, die einen TargetType- haben, werden den TargetType- als Schlüssel verwenden, falls x:Key- nicht angegeben ist. In diesem Fall ist der Schlüssel das tatsächliche Type-Objekt, keine Zeichenfolge.
  • x:Name kann an Stelle von x:Keyverwendet werden. X:Name generiert jedoch auch ein Code-behind-Feld für die Ressource. Daher ist "x:Name" weniger effizient als "x:Key", da dieses Feld beim Laden der Seite initialisiert werden muss.

Die StaticResource-Markup-Erweiterung kann Ressourcen nur mit einem Zeichenfolgenname abrufen (x:Key oder x:Name). Das XAML-Framework sucht jedoch auch nach impliziten Stilressourcen (die TargetType anstelle von x:Key oder x:Name verwenden), wenn es entscheidet, welche Formatvorlage für ein Steuerelement verwendet werden soll, das die Eigenschaften Style und ContentTemplate oder ItemTemplate nicht festgelegt hat.

Hier weist der Stil einen impliziten Schlüssel typeof(Button)auf, und da der Button unten auf der Seite keine Stileigenschaft angibt, wird nach einem Stil mit dem Schlüssel typeof(Button)gesucht:

<Page
    x:Class="MSDNSample.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <Page.Resources>
        <Style TargetType="Button">
            <Setter Property="Background" Value="Red"/>
        </Style>
    </Page.Resources>
    <Grid>
       <!-- This button will have a red background. -->
       <Button Content="Button" Height="100" VerticalAlignment="Center" Width="100"/>
    </Grid>
</Page>

Weitere Informationen zu impliziten Formatvorlagen und deren Funktionsweise finden Sie unter Formatieren von Steuerelementen und Steuerelementvorlagen.

Ressourcen im Code nachschlagen

Sie greifen auf Mitglieder des Ressourcenwörterbuchs zu wie auf jedes andere Wörterbuch.

Warnung

Wenn Sie eine Ressourcensuche im Code ausführen, werden nur die Ressourcen im Page.Resources Wörterbuch betrachtet. Im Gegensatz zur StaticResource-Markuperweiterunggreift der Code nicht auf das Application.Resources Wörterbuch zurück, wenn die Ressourcen nicht im ersten Wörterbuch gefunden werden.

 

In diesem Beispiel wird gezeigt, wie Sie die redButtonStyle Ressource aus dem Ressourcenverzeichnis einer Seite abrufen:

<Page
    x:Class="MSDNSample.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <Page.Resources>
        <Style TargetType="Button" x:Key="redButtonStyle">
            <Setter Property="Background" Value="red"/>
        </Style>
    </Page.Resources>
</Page>

    public sealed partial class MainPage : Page
    {
        public MainPage()
        {
            this.InitializeComponent();
            Style redButtonStyle = (Style)this.Resources["redButtonStyle"];
        }
    }

    MainPage::MainPage()
    {
        InitializeComponent();
        Windows::UI::Xaml::Style style = Resources().TryLookup(winrt::box_value(L"redButtonStyle")).as<Windows::UI::Xaml::Style>();
    }

Um appweite Ressourcen aus Code nachzuschlagen, verwenden Sie Application.Current.Resources , um das Ressourcenverzeichnis der App abzurufen, wie hier gezeigt.

<Application
    x:Class="MSDNSample.App"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:SpiderMSDN">
    <Application.Resources>
        <Style TargetType="Button" x:Key="appButtonStyle">
            <Setter Property="Background" Value="red"/>
        </Style>
    </Application.Resources>

</Application>

    public sealed partial class MainPage : Page
    {
        public MainPage()
        {
            this.InitializeComponent();
            Style appButtonStyle = (Style)Application.Current.Resources["appButtonStyle"];
        }
    }

    MainPage::MainPage()
    {
        InitializeComponent();
        Windows::UI::Xaml::Style style = Application::Current().Resources()
                                                               .TryLookup(winrt::box_value(L"appButtonStyle"))
                                                               .as<Windows::UI::Xaml::Style>();
    }

Sie können auch eine Anwendungsressource im Code hinzufügen.

Es gibt zwei Dinge, die Sie bei dieser Vorgehensweise beachten sollten.

  • Zuerst müssen Sie die Ressourcen hinzufügen, bevor eine Seite versucht, die Ressource zu verwenden.
  • Zweitens können Sie keine Ressourcen im Konstruktor der App hinzufügen.

Sie können beide Probleme vermeiden, wenn Sie die Ressource wie folgt in der Methode Application.OnLaunched hinzufügen.

// App.xaml.cs
    
sealed partial class App : Application
{
    protected override void OnLaunched(LaunchActivatedEventArgs e)
    {
        Frame rootFrame = Window.Current.Content as Frame;
        if (rootFrame == null)
        {
            SolidColorBrush brush = new SolidColorBrush(Windows.UI.Color.FromArgb(255, 0, 255, 0)); // green
            this.Resources["brush"] = brush;
            // … Other code that VS generates for you …
        }
    }
}

// App.cpp

void App::OnLaunched(LaunchActivatedEventArgs const& e)
{
    Frame rootFrame{ nullptr };
    auto content = Window::Current().Content();
    if (content)
    {
        rootFrame = content.try_as<Frame>();
    }

    // Do not repeat app initialization when the Window already has content,
    // just ensure that the window is active
    if (rootFrame == nullptr)
    {
        Windows::UI::Xaml::Media::SolidColorBrush brush{ Windows::UI::ColorHelper::FromArgb(255, 0, 255, 0) };
        Resources().Insert(winrt::box_value(L"brush"), winrt::box_value(brush));
        // … Other code that VS generates for you …

Jedes FrameworkElement kann ein Ressourcenverzeichnis haben.

FrameworkElement- ist eine Basisklasse, von der Steuerelemente erben, und es verfügt über eine Resources-Eigenschaft. Sie können also einem beliebigen FrameworkElement-ein lokales Ressourcenwörterbuch hinzufügen.

Hier verfügen sowohl die Page als auch der Border über Resource Dictionaries und beide über eine Ressource namens "greeting". Der TextBlock- mit dem Namen "textBlock2" befindet sich innerhalb des Border-, sodass die Ressourcensuche zuerst nach den Ressourcen des Border, dann nach den Ressourcen des Pageund dann nach den Application-Ressourcen sucht. Der TextBlock wird "Hola mundo" anzeigen.

Verwenden Sie die Resources-Eigenschaft dieses Elements, um über Code auf die Ressourcen dieses Elements zuzugreifen. Der Zugriff auf die Ressourcen eines FrameworkElement-im Code anstelle von XAML erfolgt nur in diesem Wörterbuch und nicht in den Wörterbüchern des übergeordneten Elements.

<Page
    x:Class="MSDNSample.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Page.Resources>
        <x:String x:Key="greeting">Hello world</x:String>
    </Page.Resources>
    
    <StackPanel>
        <!-- Displays "Hello world" -->
        <TextBlock x:Name="textBlock1" Text="{StaticResource greeting}"/>

        <Border x:Name="border">
            <Border.Resources>
                <x:String x:Key="greeting">Hola mundo</x:String>
            </Border.Resources>
            <!-- Displays "Hola mundo" -->
            <TextBlock x:Name="textBlock2" Text="{StaticResource greeting}"/>
        </Border>

        <!-- Displays "Hola mundo", set in code. -->
        <TextBlock x:Name="textBlock3"/>
    </StackPanel>
</Page>


    public sealed partial class MainPage : Page
    {
        public MainPage()
        {
            this.InitializeComponent();
            textBlock3.Text = (string)border.Resources["greeting"];
        }
    }

    MainPage::MainPage()
    {
        InitializeComponent();
        textBlock3().Text(unbox_value<hstring>(border().Resources().TryLookup(winrt::box_value(L"greeting"))));
    }

Zusammengeführte Ressourcenwörterbücher

Ein zusammengeführtes Ressourcenwörterbuch fügt ein Ressourcenwörterbuch in ein anderes ein, in der Regel in einer anderen Datei.

Tipp Sie können eine Ressourcenwörterbuchdatei in Microsoft Visual Studio erstellen, indem Sie im Menü > die Option "> Neues Element hinzufügen > hinzufügen... Ressourcenwörterbuch" verwenden.

Hier definieren Sie ein Ressourcenwörterbuch in einer separaten XAML-Datei namens Dictionary1.xaml.

<!-- Dictionary1.xaml -->
<ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:MSDNSample">

    <SolidColorBrush x:Key="brush" Color="Red"/>

</ResourceDictionary>

Um dieses Wörterbuch zu verwenden, führen Sie es mit dem Wörterbuch Ihrer Seite zusammen:

<Page
    x:Class="MSDNSample.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Page.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <ResourceDictionary Source="Dictionary1.xaml"/>
            </ResourceDictionary.MergedDictionaries>

            <x:String x:Key="greeting">Hello world</x:String>

        </ResourceDictionary>
    </Page.Resources>

    <TextBlock Foreground="{StaticResource brush}" Text="{StaticResource greeting}" VerticalAlignment="Center"/>
</Page>

Dies geschieht in diesem Beispiel. In <Page.Resources>deklarieren Sie <ResourceDictionary>. Das XAML-Framework erstellt implizit ein Ressourcenwörterbuch für Sie, wenn Sie Ressourcen zu <Page.Resources>hinzufügen. In diesem Fall möchten Sie jedoch ein Ressourcenwörterbuch, das zusammengeführte Wörterbücher enthält, und nicht nur irgendein Ressourcenwörterbuch.

Daher deklarieren Sie <ResourceDictionary>, dann fügen Sie der <ResourceDictionary.MergedDictionaries>-Auflistung Elemente hinzu. Jeder dieser Einträge übernimmt das Formular <ResourceDictionary Source="Dictionary1.xaml"/>. Wenn Sie mehr als ein Wörterbuch hinzufügen möchten, fügen Sie einfach einen <ResourceDictionary Source="Dictionary2.xaml"/> Eintrag nach dem ersten Eintrag hinzu.

Nach <ResourceDictionary.MergedDictionaries>…</ResourceDictionary.MergedDictionaries>können Sie optional weitere Ressourcen in Ihr Hauptwörterbuch einfügen. Sie verwenden Ressourcen aus einem zusammengeführten Wörterbuch wie ein normales Wörterbuch. Im obigen Beispiel findet {StaticResource brush} die Ressource im untergeordneten/zusammengeführten Wörterbuch (Dictionary1.xaml), während {StaticResource greeting} die Ressource im Hauptseitenwörterbuch findet.

In der Ressourcensuchsequenz wird ein MergedDictionaries- Wörterbuch erst nach einer Überprüfung aller anderen Schlüsselressourcen dieses ResourceDictionaryüberprüft. Nach dem Durchsuchen dieser Ebene erreicht die Suche die zusammengeführten Wörterbücher, und jedes Element in MergedDictionaries wird überprüft. Wenn mehrere zusammengeführte Wörterbücher vorhanden sind, werden diese Wörterbücher in der umgekehrten Reihenfolge überprüft, in der sie in der MergedDictionaries-Eigenschaft deklariert werden. Wenn im folgenden Beispiel sowohl "Dictionary2.xaml" als auch "Dictionary1.xaml" denselben Schlüssel deklariert haben, wird der Schlüssel aus "Dictionary2.xaml" zuerst verwendet, da er zuletzt im " MergedDictionaries "-Satz enthalten ist.

<Page
    x:Class="MSDNSample.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Page.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <ResourceDictionary Source="Dictionary1.xaml"/>
                <ResourceDictionary Source="Dictionary2.xaml"/>
            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </Page.Resources>

    <TextBlock Foreground="{StaticResource brush}" Text="greetings!" VerticalAlignment="Center"/>
</Page>

Innerhalb des Gültigkeitsbereichs eines ResourceDictionarywird das Wörterbuch auf die Eindeutigkeit des Schlüssels überprüft. Der Geltungsbereich erstreckt sich jedoch nicht über verschiedene Elemente in verschiedenen MergedDictionaries Dateien.

Sie können die Kombination aus der Nachschlagesequenz und fehlender eindeutiger Schlüsselerzwingung in zusammengeführten Wörterbuchbereichen verwenden, um eine Fallbackwertsequenz von ResourceDictionary Ressourcen zu erstellen. Sie können z. B. Benutzereinstellungen für eine bestimmte Pinselfarbe im letzten zusammengeführten Ressourcenverzeichnis in der Sequenz speichern, indem Sie ein Ressourcenverzeichnis verwenden, das mit den Status- und Benutzereinstellungsdaten Ihrer App synchronisiert wird. Wenn jedoch noch keine Benutzereinstellungen vorhanden sind, können Sie dieselbe Schlüsselzeichenfolge für eine ResourceDictionary Ressource in der ursprünglichen MergedDictionaries Datei definieren, und sie kann als Fallbackwert dienen. Denken Sie daran, dass jeder Wert, den Sie in einem primären Ressourcenverzeichnis angeben, immer überprüft wird, bevor die zusammengeführten Wörterbücher überprüft werden. Wenn Sie also die Fallbacktechnik verwenden möchten, definieren Sie diese Ressource nicht in einem primären Ressourcenwörterbuch.

Themenressourcen und Themenwörterbücher

Eine ThemeResource- ähnelt einer StaticResource-, aber die Ressourcensuche wird neu ausgewertet, wenn sich das Thema ändert.

In diesem Beispiel legen Sie den Vordergrund eines TextBlock- auf einen Wert aus dem aktuellen Thema fest.

<TextBlock Text="hello world" Foreground="{ThemeResource FocusVisualWhiteStrokeThemeBrush}" VerticalAlignment="Center"/>

Ein Themenwörterbuch ist ein spezieller Typ zusammengeführter Wörterbücher, der die Ressourcen enthält, die je nach Thema variieren, das ein Nutzer derzeit auf seinem Gerät verwendet. Zum Beispiel könnte das "Licht"-Thema eine weiße Farbpalette verwenden, während das "Dunkel"-Thema eine dunkle Farbpalette verwenden könnte. Der Pinsel ändert die Ressource, in die er aufgelöst wird, andernfalls kann die Zusammensetzung eines Steuerelements, das den Pinsel als Ressource verwendet, identisch sein. Um das Themenwechselverhalten in Ihren eigenen Vorlagen und Stilen zu reproduzieren, verwenden Sie anstelle der MergedDictionaries-Eigenschaft die ThemeDictionaries-Eigenschaft, um Elemente in die Hauptwörterbücher zusammenzuführen.

Jedes ResourceDictionary-Element innerhalb ThemeDictionaries- muss einen x:Key Wert aufweisen. Der Wert ist eine Zeichenfolge, die das relevante Design benennt, z. B. "Default", "Dark", "Light" oder "HighContrast". In der Regel definieren Dictionary1 und Dictionary2 Ressourcen, die dieselben Namen haben, aber unterschiedliche Werte.

Hier verwenden Sie roten Text für das helle Design und blauen Text für das dunkle Design.

<!-- Dictionary1.xaml -->
<ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:MSDNSample">

    <SolidColorBrush x:Key="brush" Color="Red"/>

</ResourceDictionary>

<!-- Dictionary2.xaml -->
<ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:MSDNSample">

    <SolidColorBrush x:Key="brush" Color="blue"/>

</ResourceDictionary>

In diesem Beispiel legen Sie den Vordergrund eines TextBlock- auf einen Wert aus dem aktuellen Thema fest.

<Page
    x:Class="MSDNSample.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Page.Resources>
        <ResourceDictionary>
            <ResourceDictionary.ThemeDictionaries>
                <ResourceDictionary Source="Dictionary1.xaml" x:Key="Light"/>
                <ResourceDictionary Source="Dictionary2.xaml" x:Key="Dark"/>
            </ResourceDictionary.ThemeDictionaries>
        </ResourceDictionary>
    </Page.Resources>
    <TextBlock Foreground="{StaticResource brush}" Text="hello world" VerticalAlignment="Center"/>
</Page>

Bei Designwörterbüchern ändert sich das aktive Wörterbuch, das für die Ressourcensuche verwendet werden soll, dynamisch, wenn ThemeResource-Markuperweiterung verwendet wird, um den Verweis vorzunehmen, und das System erkennt eine Designänderung. Das Suchverhalten, das vom System durchgeführt wird, basiert auf der Abbildung des aktiven Themas zum x:Key eines bestimmten Themenwörterbuchs.

Es kann hilfreich sein, die Art und Weise zu untersuchen, wie die Themenwörterbücher in den standardmäßigen XAML-Entwurfsressourcen strukturiert sind, die parallel zu den Vorlagen sind, die von der Windows-Runtime standardmäßig für dessen Steuerelemente verwendet werden. Öffnen Sie die XAML-Dateien in \(Program Files)\Windows Kits\10\DesignTime\CommonConfiguration\Neutral\UAP\<SDK-Version>\Generic mit einem Texteditor oder Ihrer IDE. Beachten Sie, wie die Designwörterbücher zuerst in generic.xaml definiert werden und wie jedes Designwörterbuch die gleichen Schlüssel definiert. Jeder dieser Schlüssel wird dann von Elementen der Komposition in den verschiedenen Schlüsselelementen referenziert, die sich außerhalb der Designwörterbücher befinden und später im XAML-Code definiert sind. Es gibt auch eine separate Themeresources.xaml-Datei für das Design, die nur die Designressourcen und zusätzlichen Vorlagen enthält, nicht die Standard-Steuerelementvorlagen. Die Themenbereiche sind Duplikate dessen, was Sie in "generic.xaml" sehen würden.

Wenn Sie XAML-Designtools zum Bearbeiten von Kopien von Stilen und Vorlagen verwenden, extrahieren die Designtools Abschnitte aus den XAML-Designressourcenverzeichnissen und platzieren sie als lokale Kopien von XAML-Wörterbuchelementen, die Teil Ihrer App und Ihres Projekts sind.

Weitere Informationen und eine Liste der designspezifischen und Systemressourcen, die für Ihre App verfügbar sind, finden Sie unter den XAML-Designressourcen .

Suchverhalten für XAML-Ressourcenverweise

Nachschlageverhalten ist der Begriff, der beschreibt, wie das XAML-Ressourcensystem versucht, eine XAML-Ressource zu finden. Die Suche erfolgt, wenn auf einen Schlüssel von einer beliebigen Stelle im XAML-Code der App als XAML-Ressourcenverweis verwiesen wird. Zunächst verfügt das Ressourcensystem über ein vorhersehbares Verhalten für den Ort, an dem überprüft wird, ob eine Ressource auf der Grundlage des Bereichs vorhanden ist. Wenn eine Ressource im anfänglichen Bereich nicht gefunden wird, wird der Bereich erweitert. Das Nachschlageverhalten setzt sich überall an den Orten und in den Bereichen fort, in denen eine XAML-Ressource entweder von einer App oder vom System definiert werden kann. Wenn alle möglichen Versuche der Ressourcensuche fehlschlagen, führt dies oft zu einem Fehler. Es ist in der Regel möglich, diese Fehler während des Entwicklungsprozesses zu beseitigen.

Das Nachschlageverhalten für XAML-Ressourcenverweise beginnt mit dem Objekt, an dem die tatsächliche Verwendung erfolgt, und seiner eigenen Resources-Eigenschaft. Wenn dort ein ResourceDictionary vorhanden ist, wird ResourceDictionary auf ein Element überprüft, das den angeforderten Schlüssel aufweist. Diese erste Suchebene ist selten relevant, da Sie normalerweise keine Ressource auf demselben Objekt definieren und dann darauf verweisen. Tatsächlich gibt es hier häufig keine Resources-Eigenschaft. Sie können XAML-Ressourcenverweise nahezu überall in XAML erstellen; Sie sind nicht auf Eigenschaften von FrameworkElement Unterklassen beschränkt.

Die Suchsequenz überprüft dann das nächste übergeordnete Objekt im Laufzeitobjektbaum der App. Wenn ein FrameworkElement.Resources vorhanden ist und ein ResourceDictionaryenthält, wird das Wörterbuch-Element mit der angegebenen Schlüsselzeichenfolge angefordert. Wenn die Ressource gefunden wird, wird die Nachschlagesequenz beendet, und das Objekt wird an der Position bereitgestellt, an der der Verweis erstellt wurde. Andernfalls wechselt das Nachschlageverhalten zur nächsten übergeordneten Ebene zum Stamm der Objektstruktur. Die Suche wird rekursiv nach oben fortgesetzt, bis das Stammelement des XAML erreicht ist und alle möglichen unmittelbaren Ressourcenspeicherorte vollständig durchsucht sind.

Hinweis

Es ist üblich, alle unmittelbaren Ressourcen auf der Stammebene einer Seite zu definieren, sowohl um dieses Ressourcen-Nachschlageverhalten als auch als Konvention des XAML-Markupstils zu nutzen.

Wenn die angeforderte Ressource in den direkten Ressourcen nicht gefunden wird, besteht der nächste Schritt beim Nachschlagen darin, die Application.Resources-Eigenschaft zu überprüfen. Application.Resources ist der beste Ort, um appspezifische Ressourcen zu platzieren, auf die von mehreren Seiten in der Navigationsstruktur Ihrer App verwiesen wird.

Von Bedeutung

Die Reihenfolge der Ressourcen, die einem ResourceDictionary hinzugefügt werden, wirkt sich auf die Reihenfolge aus, in der sie angewendet werden. Das XamlControlsResources-Wörterbuch setzt viele Standardressourcenschlüssel außer Kraft und sollte daher zuerst zu Application.Resources hinzugefügt werden, damit es keine anderen benutzerdefinierten Stile oder Ressourcen in Ihrer App außer Kraft setzt.

Steuerelementvorlagen haben einen weiteren möglichen Standort in der Referenzsuche: Themenwörterbücher. Ein Designwörterbuch ist eine einzelne XAML-Datei, die ein ResourceDictionary Element als Stammelement enthält. Das Themenwörterbuch könnte ein zusammengeführtes Wörterbuch aus Application.Resourcessein. Das Designwörterbuch kann auch das steuerelementspezifische Designwörterbuch für ein benutzerdefiniertes Steuerelement mit Vorlagen sein.

Schließlich erfolgt ein Zugriff auf die Plattformressourcen. Plattformressourcen umfassen die Steuerelementvorlagen, die für jedes der System-UI-Designs definiert sind und die die Standarddarstellung aller Steuerelemente definieren, die Sie für die Benutzeroberfläche in einer Windows-Runtime-App verwenden. Plattformressourcen umfassen auch eine Reihe benannter Ressourcen, die sich auf das systemweite Erscheinungsbild und die Themen beziehen. Diese Ressourcen sind technisch eine MergedDictionaries Element und stehen daher nach dem Laden der App aus XAML oder Code zur Verfügung. Die Systemdesign-Ressourcen enthalten z. B. eine Ressource mit dem Namen "SystemColorWindowTextColor", die eine Color Definition liefert, um die Textfarbe einer App an die Textfarbe eines Systemfensters anzupassen, die aus den Einstellungen des Betriebssystems und der Benutzerpräferenzen resultiert. Andere XAML-Formatvorlagen für Ihre App können auf diese Formatvorlage verweisen, oder Ihr Code kann einen Ressourcensuchwert abrufen (und in Color im Beispielfall umwandeln).

Weitere Informationen und eine Liste der designspezifischen und Systemressourcen, die für eine Windows-App verfügbar sind, die XAML verwendet, finden Sie unter XAML-Designressourcen.

Wenn der angeforderte Schlüssel an keinem dieser Speicherorte gefunden wird, tritt ein XAML-Analysefehler/eine Ausnahme auf. Unter bestimmten Umständen kann es sich bei der XAML-Parse-Ausnahme um einen Laufzeitfehler handeln, der weder durch eine XAML-Markupkompilierungsaktion noch durch eine XAML-Entwurfsumgebung erkannt wird.

Aufgrund des mehrstufigen Suchverhaltens für Ressourcenwörterbücher können Sie absichtlich mehrere Ressourcenelemente definieren, die jeweils den gleichen Zeichenfolgenwert wie der Schlüssel aufweisen, solange jede Ressource auf einer anderen Ebene definiert ist. Anders ausgedrückt: Obwohl Schlüssel innerhalb eines bestimmten ResourceDictionaryeindeutig sein müssen, erstreckt sich die Eindeutigkeitsanforderung nicht auf den Ablauf des Nachschlageverhaltens als Ganzes. Bei der Suche wird nur das erste objekt, das erfolgreich abgerufen wird, für den XAML-Ressourcenverweis verwendet, und dann wird die Suche beendet. Sie können dieses Verhalten nutzen, um bei verschiedenen Positionen innerhalb des XAMLs Ihrer App dieselbe XAML-Ressource nach Schlüssel anzufordern. Abhängig vom Bereich, aus dem der XAML-Ressourcenverweis stammt, und davon, wie genau diese Suche durchgeführt wird, können unterschiedliche Ressourcen zurückgegeben werden.

Weiterleiten von Verweisen in einem ResourceDictionary

XAML-Ressourcenverweise innerhalb eines bestimmten Ressourcenwörterbuchs müssen auf eine Ressource verweisen, die bereits mit einem Schlüssel definiert wurde, und diese Ressource muss lexikalisch vor dem Ressourcenverweis angezeigt werden. Vorwärtsreferenzen können nicht durch einen XAML-Ressourcenverweis aufgelöst werden. Aus diesem Grund müssen Sie, wenn Sie XAML-Ressourcenverweise aus einer anderen Ressource verwenden, ihre Ressourcenverzeichnisstruktur so entwerfen, dass die ressourcen, die von anderen Ressourcen verwendet werden, zuerst in einem Ressourcenwörterbuch definiert werden.

Ressourcen, die auf App-Ebene definiert sind, können keine Verweise auf sofortige Ressourcen erstellen. Dies entspricht dem Versuch eines Vorwärtsverweises, da die App-Ressourcen zuerst verarbeitet werden (beim ersten Start der App und vor dem Laden von Navigationsseiteninhalten). Jede sofortige Ressource kann jedoch einen Verweis auf eine App-Ressource erstellen, und dies kann eine nützliche Technik sein, um Vorwärtsverweissituationen zu vermeiden.

XAML-Ressourcen müssen gemeinsam verwendet werden können

Damit ein Objekt in einem ResourceDictionary-existieren kann, muss es teilbarsein.

Es ist erforderlich, dass Objekte teilbar sind, da sie nicht an mehreren Stellen in der Struktur vorhanden sein können, wenn die Objektstruktur einer App zur Laufzeit erstellt und verwendet wird. Intern erstellt das Ressourcensystem Kopien von Ressourcenwerten, die im Objektdiagramm Ihrer App verwendet werden sollen, wenn jede XAML-Ressource angefordert wird.

Ein ResourceDictionary und Windows-Runtime-XAML unterstützt im allgemeinen diese Objekte für die gemeinsame Nutzung:

Sie können auch benutzerdefinierte Typen als gemeinsam nutzbare Ressource verwenden, wenn Sie den erforderlichen Implementierungsmustern folgen. Sie definieren solche Klassen in Ihrem Sicherungscode (oder in von Ihnen eingeschlossenen Laufzeitkomponenten) und instanziieren diese Klassen dann in XAML als Ressource. Beispiele sind Objektdatenquellen und Implementierungen von IValueConverter für die Datenbindung.

Benutzerdefinierte Typen müssen über einen Standardkonstruktor verfügen, da dies die Methode ist, die ein XAML-Parser verwendet, um eine Klasse zu instanziieren. Benutzerdefinierte Typen, die als Ressourcen verwendet werden, können nicht über die UIElement- Klasse in ihrer Vererbung verfügen, da ein UIElement- niemals freigegeben werden kann (es ist immer beabsichtigt, genau ein UI-Element darzustellen, das an einer Position im Objektdiagramm Ihrer Laufzeit-App vorhanden ist).

UserControl-Verwendungsbereich

Ein UserControl--Element weist eine besondere Situation für das Ressourcensucheverhalten auf, da es über die inhärenten Konzepte eines Definitionsbereichs und eines Verwendungsbereichs verfügt. Ein UserControl-, das einen XAML-Ressourcenverweis aus seinem Definitionsbereich erstellt, muss in der Lage sein, die Suche dieser Ressource innerhalb ihrer eigenen Definitionsbereich-Nachschlagesequenz zu unterstützen, d. h., sie kann nicht auf App-Ressourcen zugreifen. Aus dem Nutzungsbereich eines UserControls wird ein Ressourcenverweis innerhalb der Nachschlagesequenz in Richtung des Wurzelpunkts der Verwendungsseite behandelt (ähnlich wie jeder andere Ressourcenverweis, der von einem Objekt in einer geladenen Objektstruktur gemacht wird) und kann auf Anwendungsressourcen zugreifen.

"ResourceDictionary" und "XamlReader.Load"

Sie können ein ResourceDictionary entweder als Wurzel oder als Teil der XAML-Eingabe für die Methode XamlReader.Load verwenden. Sie können auch XAML-Ressourcenverweise in diesen XAML-Code einschließen, sofern alle derartigen Verweise vollständig in dem zur Verarbeitung eingereichten XAML-Code enthalten sind. XamlReader.Load analysiert den XAML-Code in einem Kontext, der keine anderen ResourceDictionary-Objekte kennt, nicht einmal Application.Resources. Verwenden Sie {ThemeResource} auch nicht innerhalb von XAML, das an XamlReader.Loadübermittelt wurde.

Verwenden eines ResourceDictionary aus Code

Die meisten Szenarien für ein ResourceDictionary- werden ausschließlich in XAML behandelt. Sie deklarieren den ResourceDictionary-Container und die Ressourcen als XAML-Datei oder xaml-Knoten in einer UI-Definitionsdatei. Anschließend verwenden Sie XAML-Ressourcenverweise, um diese Ressourcen aus anderen Teilen von XAML anzufordern. Dennoch gibt es bestimmte Szenarien, in denen Ihre App den Inhalt eines ResourceDictionary mithilfe von Code anpassen möchte, der während der Ausführung der App ausgeführt wird, oder zumindest um den Inhalt eines ResourceDictionary abzufragen, um festzustellen, ob eine Ressource bereits definiert ist. Diese Codeaufrufe werden bei einer ResourceDictionary Instanz ausgeführt, daher müssen Sie zuerst eines abrufen – entweder ein direktes ResourceDictionary irgendwo in der Objektstruktur, indem Sie FrameworkElement.Resourcesabrufen, oder Application.Current.Resources.

In C# oder Microsoft Visual Basic-Code können Sie mithilfe des Indexers (Item) auf eine Ressource in einem ResourceDictionary verweisen. Ein ResourceDictionary ist ein Wörterbuch mit Zeichenfolgen als Schlüssel, sodass der Indexer den Zeichenfolgenschlüssel anstelle eines ganzzahligen Index verwendet. Verwenden Sie in Visual C++-Komponentenerweiterungen (C++/CX)-Code Nachschlage-.

Wenn Sie Code zum Untersuchen oder Ändern eines ResourceDictionary-verwenden, wird das Verhalten für APIs wie Lookup oder Item nicht von direkten Ressourcen zu App-Ressourcen durchlaufen; dies ist ein XAML-Parserverhalten, das nur auftritt, wenn XAML-Seiten geladen werden. Zur Laufzeit ist der Bereich für Schlüssel auf die Instanz von ResourceDictionary beschränkt, die Sie gerade verwenden. Der Umfang erstreckt sich jedoch in MergedDictionarieshinein.

Wenn Sie auch einen Schlüssel anfordern, der im ResourceDictionary nicht vorhanden ist, tritt möglicherweise kein Fehler auf. Der Rückgabewert kann einfach als NULL angegeben werden. Wenn Sie jedoch versuchen, den zurückgegebenen null als Wert zu verwenden, kann dennoch ein Fehler auftreten. Der Fehler stammt aus dem Setter der Eigenschaft, nicht vom Aufruf des ResourceDictionary. Die einzige Möglichkeit, einen Fehler zu vermeiden, wäre, wenn die Eigenschaft null als gültigen Wert akzeptieren würde. Beachten Sie, wie sich dieses Verhalten mit dem XAML-Nachschlageverhalten zur XAML-Analysezeit unterscheidet. Ein Fehler beim Beheben des bereitgestellten Schlüssels aus XAML zur Analysezeit führt zu einem XAML-Analysefehler, auch in Fällen, in denen die Eigenschaft NULL-akzeptiert haben könnte.

Zusammengeführte Ressourcenwörterbücher sind im Indexbereich des primären Ressourcenwörterbuchs enthalten, das zur Laufzeit auf das zusammengeführte Wörterbuch verweist. Mit anderen Worten: Sie können Eintrag oder die Suche des primären Wörterbuchs verwenden, um alle Objekte zu finden, die tatsächlich im zusammengeführten Wörterbuch definiert wurden. In diesem Fall ähnelt das Nachschlageverhalten dem Analysezeit-XAML-Nachschlageverhalten: Wenn mehrere Objekte in zusammengeführten Wörterbüchern vorhanden sind, die jeweils denselben Schlüssel aufweisen, wird das Objekt aus dem zuletzt hinzugefügten Wörterbuch zurückgegeben.

Sie dürfen einem vorhandenen ResourceDictionary Elemente hinzufügen, indem Sie Add (C# oder Visual Basic) oder Insert (C++/CX) aufrufen. Sie können die Elemente entweder unmittelbaren Ressourcen oder App-Ressourcen hinzufügen. Eine dieser API-Aufrufe erfordert einen Schlüssel, der die Anforderung erfüllt, dass jedes Element in einem ResourceDictionary über einen Schlüssel verfügt. Jedoch sind Elemente, die Sie einem ResourceDictionary- zur Laufzeit hinzufügen, für XAML-Ressourcenverweise nicht relevant. Die erforderliche Suche für XAML-Ressourcenverweise erfolgt, wenn xaml zum ersten Mal analysiert wird, wenn die App geladen wird (oder eine Designänderung erkannt wird). Ressourcen, die zur Laufzeit Sammlungen hinzugefügt wurden, waren dann nicht verfügbar, und eine Änderung des ResourceDictionary macht eine bereits abgerufene Ressource nicht ungültig, auch wenn Sie den Wert dieser Ressource ändern.

Sie können auch Elemente aus einem ResourceDictionary- zur Laufzeit entfernen, Kopien einiger oder aller Elemente erstellen oder andere Vorgänge durchführen. Die Mitgliederauflistung für ResourceDictionary gibt an, welche APIs verfügbar sind. Beachten Sie, dass ResourceDictionary über eine projizierte API verfügt, um die zugrunde liegenden Sammlungsschnittstellen zu unterstützen. Die API-Optionen unterscheiden sich je nachdem, ob Sie C# oder Visual Basic oder C++/CX verwenden.

ResourceDictionary und Lokalisierung

Ein XAML-ResourceDictionary- kann anfänglich Zeichenfolgen enthalten, die lokalisiert werden sollen. Wenn ja, speichern Sie diese Zeichenfolgen als Projektressourcen anstatt in einem ResourceDictionary. Nehmen Sie die Zeichenfolgen aus dem XAML-Code heraus, und weisen Sie stattdessen dem eigenen Element eine x:Uid-Direktive Wert zu. Definieren Sie dann eine Ressource in einer Ressourcendatei. Geben Sie einen Ressourcennamen im Format XUIDValue-PropertyName an und geben Sie einen Ressourcenwert für die Zeichenfolge an, die lokalisiert werden muss.

Benutzerdefinierte Ressourcensuche

Für erweiterte Szenarien können Sie eine Klasse implementieren, die ein anderes Verhalten aufweisen kann als das in diesem Thema beschriebene XAML-Ressourcenreferenz-Nachschlageverhalten. Dazu implementieren Sie die Klasse CustomXamlResourceLoader, und dann können Sie mithilfe der CustomResource-Markuperweiterung für Ressourcenverweise auf dieses Verhalten zugreifen, anstatt StaticResource oder ThemeResourcezu verwenden. Die meisten Apps verfügen nicht über Szenarien, die dies erfordern. Weitere Informationen finden Sie unter CustomXamlResourceLoader.