{ThemeResource}-Markuperweiterung

Stellt einen Wert für jedes XAML-Attribut bereit, indem ein Verweis auf eine Ressource ausgewertet wird, mit zusätzlicher Systemlogik, die je nach aktuell aktivem Thema unterschiedliche Ressourcen abruft. Ähnlich wie die {StaticResource}-Markuperweiterung werden Ressourcen in einem ResourceDictionary definiert, und eine ThemeResource-Verwendung verweist auf den Schlüssel dieser Ressource im ResourceDictionary.

XAML-Attributverwendung

<object property="{ThemeResource key}" .../>

XAML-Werte

Bemerkungen

Eine ThemeResource ist eine Technik zum Abrufen von Werten für ein XAML-Attribut, die an anderer Stelle in einem XAML-Ressourcenwörterbuch definiert sind. Die Markuperweiterung dient dem gleichen grundlegenden Zweck wie die {StaticResource}-Markuperweiterung. Der Unterschied im Verhalten gegenüber der {StaticResource}-Markuperweiterung besteht darin, dass ein ThemeResource-Verweis verschiedene Wörterbücher dynamisch als primären Nachschlageort verwenden kann, je nachdem, welches Design derzeit vom System verwendet wird.

Wenn die App zum ersten Mal gestartet wird, wird jeder Ressourcenverweis, der von einem ThemeResource-Verweis erstellt wird, basierend auf dem Design ausgewertet, das beim Start verwendet wird. Wenn der Benutzer das aktive Design jedoch zur Laufzeit ändert, wertet das System alle ThemeResource-Verweise erneut aus, ruft eine designspezifische Ressource ab, die möglicherweise anders sein kann, und zeigt die App an allen geeigneten Stellen in der visuellen Struktur erneut an. Eine StaticResource wird zum XAML-Ladezeitpunkt /App-Start bestimmt und wird zur Laufzeit nicht erneut ausgewertet. (Es gibt andere Techniken wie visuelle Zustände, die XAML dynamisch neu laden, aber diese Techniken funktionieren auf einer höheren Ebene, als die grundlegende Ressourcenauswertung durch die {StaticResource}-Markuperweiterung aktiviert wurde).

ThemeResource verwendet ein Argument, das den Schlüssel für die angeforderte Ressource angibt. Ein Ressourcenschlüssel ist immer eine Zeichenfolge in Windows-Runtime-XAML. Weitere Informationen dazu, wie der Ressourcenschlüssel anfänglich angegeben wird, finden Sie unter "x:Key"-Attribut.

Weitere Informationen zum Definieren von Ressourcen und zur ordnungsgemäßen Verwendung eines ResourceDictionary, einschließlich Beispielcode, finden Sie unter ResourceDictionary- und XAML-Ressourcenverweise.

Wichtig Wie bei StaticResource darf eine ThemeResource nicht versuchen, einen Vorwärtsverweis auf eine Ressource vorzunehmen, die in der XAML-Datei lexikalisch definiert ist. Der Versuch, dies zu tun, wird nicht unterstützt. Auch wenn der Vorwärtsverweis nicht fehlschlägt, bringt der Versuch, einen zu erstellen, eine Leistungseinbuße mit sich. Um optimale Ergebnisse zu erzielen, passen Sie die Zusammensetzung Ihrer Ressourcenwörterbücher so an, dass Vorwärtsverweise vermieden werden.

Beim Versuch, eine ThemeResource für einen Schlüssel anzugeben, der nicht aufgelöst werden kann, wird zur Laufzeit eine XAML-Analyseausnahme ausgelöst. Designtools können auch Warnungen oder Fehler enthalten.

In der XAML-Prozessorimplementierung der Windows-Runtime gibt es keine Sicherungsklassendarstellung für ThemeResource. Die nächstgelegene Entsprechung im Code besteht darin, die Sammlungs-API eines ResourceDictionary zu verwenden, z. B. "Contains" oder "*TryGetValue".

ThemeResource ist eine Markuperweiterung. Markuperweiterungen werden in der Regel implementiert, wenn es erforderlich ist, Attributwerte, die weder Literalwerte noch Handlernamen sind, zu escapen, und die Anforderung umfassender ist als nur das Platzieren von Typkonvertern bei bestimmten Typen oder Eigenschaften. Alle Markuperweiterungen in XAML verwenden die Zeichen "{" und "}" in ihrer Attributsyntax. Dies ist die Konvention, mit der ein XAML-Prozessor erkennt, dass eine Markuperweiterung das Attribut verarbeiten muss.

Wann und wie {ThemeResource} anstelle von {StaticResource} verwendet wird

Die Regeln, nach denen eine ThemeResource in ein Element in einem Ressourcenwörterbuch aufgelöst wird, sind im Allgemeinen mit StaticResource identisch. Eine ThemeResource-Suche kann in die ResourceDictionary-Dateien erweitert werden, auf die in einer ThemeDictionaries-Auflistung verwiesen wird, aber eine StaticResource kann dies auch tun. Der Unterschied besteht darin, dass eine ThemeResource zur Laufzeit neu ausgewertet werden kann und eine StaticResource nicht möglich ist.

Der Satz von Schlüsseln in jedem Themendictionary sollte den gleichen Satz von Schlüsselressourcen bereitstellen, egal welches Thema aktiviert ist. Wenn eine bestimmte Schlüsselressource im Designverzeichnis "HighContrast " vorhanden ist, sollte auch eine andere Ressource mit diesem Namen in Light und Default vorhanden sein. Wenn dies nicht der Fall ist, schlägt die Ressourcensuche möglicherweise fehl, wenn der Benutzer Designs wechselt und Ihre App nicht richtig aussieht. Es ist jedoch möglich, dass ein Designwörterbuch Schlüsselressourcen enthalten kann, auf die nur innerhalb desselben Bereichs verwiesen wird, um Unterwerte bereitzustellen; Diese müssen in allen Designs nicht gleichwertig sein.

Im Allgemeinen sollten Sie Ressourcen in Designwörterbüchern platzieren und Verweise auf diese Ressourcen mit ThemeResource nur erstellen, wenn diese Werte zwischen Designs geändert werden können oder von Werten unterstützt werden, die sich ändern. Dies ist für diese Arten von Ressourcen geeignet:

• Pinsel, insbesondere Farben für SolidColorBrush. Diese bilden etwa 80% der ThemeResource-Verwendungen in den Standard-XAML-Steuerelementvorlagen (generic.xaml).
• Pixelwerte für Rahmen, Offsets, Rand und Abstand usw.
• Schriftarteigenschaften wie FontFamily oder FontSize.
• Vollständige Vorlagen für eine begrenzte Anzahl von Steuerelementen, die in der Regel systemformatiert sind und für dynamische Präsentationen verwendet werden, z. B. GridViewItem und ListViewItem.
• Textanzeigeformate (in der Regel zum Ändern der Schriftfarbe, des Hintergrunds und eventueller Größe).

Die Windows-Runtime stellt eine Reihe von Ressourcen bereit, auf die speziell von ThemeResource verwiesen werden soll. Diese werden alle als Teil der XAML-Datei themeresources.xaml aufgeführt, die im Ordner include/winrt/xaml/design im Rahmen des Windows Software Development Kit (SDK) verfügbar ist. Dokumentation zu den Designpinseln und zusätzlichen Formatvorlagen, die in themeresources.xaml definiert sind, finden Sie unter XAML-Designressourcen. Die Pinsel sind in einer Tabelle dokumentiert, die Ihnen anzeigt, welchen Farbwert jeder Pinsel bei jedem der drei möglichen aktiven Themen hat.

Die XAML-Definitionen visueller Zustände in einer Steuerelementvorlage sollten ThemeResource-Verweise verwenden, wenn eine zugrunde liegende Ressource vorhanden ist, die sich aufgrund einer Designänderung ändern kann. Eine Änderung des Systemthemas verursacht normalerweise nicht auch eine Änderung des visuellen Zustands. Die Ressourcen müssen ThemeResource-Verweise in diesem Fall verwenden, damit Werte für den weiterhin aktiven visuellen Zustand neu ausgewertet werden können. Wenn Sie z. B. einen visuellen Zustand haben, der eine Pinselfarbe eines bestimmten UI-Teils und eine seiner Eigenschaften ändert und diese Pinselfarbe pro Design unterschiedlich ist, sollten Sie einen ThemeResource-Verweis verwenden, um den Wert dieser Eigenschaft in der Standardvorlage und auch alle Änderungen des visuellen Zustands an dieser Standardvorlage bereitzustellen.

ThemeResource-Verwendungen können in einer Reihe von abhängigen Werten angezeigt werden. Beispielsweise kann ein von einem SolidColorBrush verwendeter Farbwert, der auch eine Schlüsselressource ist, einen ThemeResource-Verweis verwenden. Aber alle UI-Eigenschaften, die die schlüssel-basierte SolidColorBrush-Ressource verwenden, würden auch einen ThemeResource-Verweis verwenden, sodass es sich speziell um jede Pinsel-Typ-Eigenschaft handelt, die eine dynamische Wertänderung ermöglicht, wenn sich das Design ändert.

Anmerkung{ThemeResource} Die Laufzeitressourcenauswertung beim Themenwechsel wird in Windows 8.1 XAML unterstützt, jedoch nicht in XAML für Apps, die auf Windows 8 abzielen.

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. Beispielsweise gibt es eine Systemressource namens "SystemColorButtonFaceColor", die eine RGB-Farbe darstellt. Diese Farbe stammt aus den Aspekten von Systemfarben und Designs, die nicht nur für Windows-Runtime- und Windows-Runtime-Apps spezifisch sind.

Systemressourcen sind häufig die zugrunde liegenden Werte für ein Design mit hohem Kontrast. Der Benutzer hat die Kontrolle über die Farbauswahl für sein Design mit hohem Kontrast, und der Benutzer trifft diese Auswahl mithilfe von Systemfeatures, die auch nicht für Windows-Runtime-Apps spezifisch sind. Durch Verweisen auf die Systemressourcen als ThemeResource-Verweise kann das Standardverhalten der Designs mit hohem Kontrast für Windows-Runtime-Apps diese designspezifischen Werte verwenden, die vom Benutzer gesteuert und vom System verfügbar gemacht werden. Außerdem werden die Verweise jetzt für die erneute Auswertung markiert, wenn das System eine Laufzeitdesignänderung erkennt.

Beispiel für eine {ThemeResource}-Verwendung

Nachfolgend finden Sie ein Beispiel-XAML aus den Standarddateien "generic.xaml" und "themeresources.xaml", um zu veranschaulichen, wie ThemeResource verwendet wird. Wir betrachten nur eine Vorlage (die Standardschaltfläche) und wie zwei Eigenschaften deklariert werden (Hintergrund und Vordergrund), um auf Designänderungen reagieren zu können.

    <!-- Default style for Windows.UI.Xaml.Controls.Button -->
    <Style TargetType="Button">
        <Setter Property="Background" Value="{ThemeResource ButtonBackgroundThemeBrush}" />
        <Setter Property="Foreground" Value="{ThemeResource ButtonForegroundThemeBrush}"/>
...

Hier nehmen die Eigenschaften einen Pinselwert an, und der Verweis auf SolidColorBrush-Ressourcen namens ButtonBackgroundThemeBrush und ButtonForegroundThemeBrush wird mithilfe von ThemeResource erstellt.

Diese Eigenschaften werden auch von einigen visuellen Zuständen für eine Schaltfläche angepasst. Insbesondere ändert sich die Hintergrundfarbe, wenn auf eine Schaltfläche geklickt wird. Auch hier verwenden die Hintergrund- und Vordergrund-Animationen im Storyboard für den visuellen Zustand DiskreteObjektKeyFrame-Objekte und Verweise auf Pinsel mit ThemeResource als Keyframe-Wert.

<VisualState x:Name="Pressed">
  <Storyboard>
    <ObjectAnimationUsingKeyFrames Storyboard.TargetName="Border"
        Storyboard.TargetProperty="Background">
      <DiscreteObjectKeyFrame KeyTime="0" Value="{ThemeResource ButtonPressedBackgroundThemeBrush}" />
    </ObjectAnimationUsingKeyFrames>
    <ObjectAnimationUsingKeyFrames Storyboard.TargetName="ContentPresenter"
         Storyboard.TargetProperty="Foreground">
       <DiscreteObjectKeyFrame KeyTime="0" Value="{ThemeResource ButtonPressedForegroundThemeBrush}" />
    </ObjectAnimationUsingKeyFrames>
  </Storyboard>
</VisualState>

Jeder dieser Pinsel ist früher in "generic.xaml" definiert: Sie mussten vor ihrer Verwendung in Vorlagen definiert werden, um XAML-Weiterleitungsverweise zu vermeiden. Hier sind die Definitionen für das Themenwörterbuch "Standard".

    <ResourceDictionary.ThemeDictionaries>
        <ResourceDictionary x:Key="Default">
...
            <SolidColorBrush x:Key="ButtonBackgroundThemeBrush" Color="Transparent" />
            <SolidColorBrush x:Key="ButtonForegroundThemeBrush" Color="#FFFFFFFF" />
...
            <SolidColorBrush x:Key="ButtonPressedBackgroundThemeBrush" Color="#FFFFFFFF" />
            <SolidColorBrush x:Key="ButtonPressedForegroundThemeBrush" Color="#FF000000" />
...

Auch in den anderen Themenwörterbüchern sind diese Pinsel definiert, z. B.:

        <ResourceDictionary x:Key="HighContrast">
            <!-- High Contrast theme resources -->
...
            <SolidColorBrush x:Key="ButtonBackgroundThemeBrush" Color="{ThemeResource SystemColorButtonFaceColor}" />
            <SolidColorBrush x:Key="ButtonForegroundThemeBrush" Color="{ThemeResource SystemColorButtonTextColor}" />

...
            <SolidColorBrush x:Key="ButtonPressedBackgroundThemeBrush" Color="{ThemeResource SystemColorButtonTextColor}" />
            <SolidColorBrush x:Key="ButtonPressedForegroundThemeBrush" Color="{ThemeResource SystemColorButtonFaceColor}" />

Hier ist der Farbwert ein weiterer ThemeResource-Verweis auf eine Systemressource. Wenn Sie auf eine Systemressource verweisen und möchten, dass sie sich als Reaktion auf eine Themenänderung ändert, sollten Sie ThemeResource verwenden, um den Verweis vorzunehmen.

Unterstützung von Entwurfszeittools für die {ThemeResource} -Markuperweiterung

Microsoft Visual Studio kann mögliche Schlüsselwerte in die Microsoft IntelliSense-Dropdowns einschließen, wenn Sie die {ThemeResource} -Markuperweiterung auf einer XAML-Seite verwenden. Sobald Sie z. B. "{ThemeResource" eingeben, werden alle Ressourcenschlüssel aus den XAML-Designressourcen angezeigt.

Sobald ein Ressourcenschlüssel als Teil einer {ThemeResource}-Verwendung vorhanden ist, kann das Feature Gehe zu Definition (F12) diese Ressource auflösen und Ihnen die generic.xaml für die Entwurfszeit anzeigen, in der die Themenressource definiert ist. Da Designressourcen mehr als einmal (pro Thema) definiert werden, führt Gehe zu Definition Sie zur ersten in der Datei gefundenen Definition, die die Definition für Default ist. Wenn Sie die anderen Definitionen finden möchten, können Sie innerhalb der Datei nach dem Schlüsselnamen suchen und die Definitionen der anderen Themen finden.

Zugehörige Themen

• Ressourcen-Wörterbuch und XAML-Ressourcenverweise
• XAML-Designressourcen
• ResourceDictionary
• x:Key-Attribut