XAML-Themenressourcen

Designressourcen in XAML sind eine Gruppe von Ressourcen, die unterschiedliche Werte anwenden, je nachdem, welches Systemdesign aktiv ist. Es gibt drei Designs, die vom XAML-Framework unterstützt werden: "Light", "Dark" und "HighContrast".

Voraussetzungen: In diesem Thema wird davon ausgegangen, dass Sie ResourceDictionary- und XAML-Ressourcenverweise gelesen haben.

Designressourcen v. statische Ressourcen

Es gibt zwei XAML-Markuperweiterungen, die aus einem vorhandenen XAML-Ressourcenwörterbuch auf eine XAML-Ressource verweisen können: {StaticResource}-Markuperweiterung und {ThemeResource}-Markuperweiterung.

Die Auswertung einer {ThemeResource}-Markuperweiterung erfolgt, wenn die App jedes Mal geladen wird, wenn sich das Design zur Laufzeit ändert. Dies ist in der Regel das Ergebnis, dass der Benutzer seine Geräteeinstellungen oder eine programmgesteuerte Änderung innerhalb der App ändert, die das aktuelle Design ändert.

Im Gegensatz dazu wird eine {StaticResource}-Markuperweiterung nur ausgewertet, wenn der XAML-Code zuerst von der App geladen wird. Es wird nicht aktualisiert. Es ähnelt einem Suchen und Ersetzen in Xaml durch den tatsächlichen Laufzeitwert beim Starten der App.

Designressourcen in der Ressourcenverzeichnisstruktur

Jede Designressource ist Teil der XAML-Datei "themeresources.xaml". Für Entwurfszwecke steht themeresources.xaml in der Installation \(Programme)\Windows Kits\10\DesignTime\CommonConfiguration\Neutral\UAP\<SDK version>\Generic aus einer Windows Software Development Kit (SDK)-Installation zur Verfügung. Die Ressourcenwörterbücher in themeresources.xaml werden auch in generic.xaml im selben Verzeichnis reproduziert.

Die Windows-Runtime verwendet diese physischen Dateien nicht für die Laufzeitsuche. Deshalb befinden sie sich speziell in einem DesignTime-Ordner und werden nicht standardmäßig in Apps kopiert. Stattdessen sind diese Ressourcenwörterbücher im Arbeitsspeicher als Teil der Windows-Runtime selbst vorhanden, und die XAML-Ressourcenverweise Ihrer App auf Designressourcen (oder Systemressourcen) werden zur Laufzeit aufgelöst.

Richtlinien für benutzerdefinierte Designressourcen

Befolgen Sie diese Richtlinien, wenn Sie Ihre eigenen benutzerdefinierten Designressourcen definieren und nutzen:

• Geben Sie zusätzlich zu Ihrem "HighContrast"-Wörterbuch Designwörterbücher für "Hell" und "Dunkel" an. Obwohl Sie ein ResourceDictionary mit "Default" als Schlüssel erstellen können, wird es bevorzugt, explizit zu sein und stattdessen "Light", "Dark" und "HighContrast" zu verwenden.

• Verwenden Sie die {ThemeResource}-Markuperweiterung in: Stile, Setter, Steuerelementvorlagen, Eigenschaftensatzer und Animationen.

• Verwenden Sie die {ThemeResource}-Markuperweiterung nicht in Ihren Ressourcendefinitionen in Ihren ThemeDictionaries. Verwenden Sie stattdessen die Markuperweiterung {StaticResource} .

  AUSNAHME: Sie können die {ThemeResource}-Markuperweiterung verwenden, um auf Ressourcen zu verweisen, die für das App-Design in Ihren ThemeDictionaries agnostisch sind. Beispiele für diese Ressourcen sind Akzentfarbressourcen wie SystemAccentColorz. B. Systemfarbressourcen oder Systemfarbressourcen, die in der Regel mit dem Präfix "SystemColor" vorangestellt werden.SystemColorButtonFaceColor

Die XAML-Farbhierarchie und designabhängige Pinsel

Die kombinierten Farben für designs "Light", "Dark" und "HighContrast" bilden die Windows-Farbhierarchie in XAML. Ganz gleich, ob Sie die Systemdesigns ändern oder ein Design auf Ihre eigenen XAML-Elemente anwenden möchten, es ist wichtig zu verstehen, wie die Farbressourcen strukturiert sind.

Weitere Informationen zum Anwenden von Farben in Ihrer Windows-App finden Sie unter "Farbe" in Windows-Apps.

Helle und dunkle Designfarben

Das XAML-Framework stellt einen Satz benannter Farbressourcen mit Werten bereit, die auf die Designs "Light" und "Dark" zugeschnitten sind. Für WinUI 2 werden die Designressourcen in der Xaml-Datei "Common theme resources" definiert. Die Farbnamen sind sehr beschreibend für ihre beabsichtigte Verwendung, und es gibt eine entsprechende SolidColorBrush-Ressource für jede Color-Ressource.

Die WinUI 3 Gallery-App enthält interaktive Beispiele für die meisten WinUI 3-Steuerelemente, -Features und -Funktionen. Abrufen der App aus dem Microsoft Store oder Abrufen des Quellcodes auf GitHub

Designfarben für Windows-Systemkontrast

Zusätzlich zu den Ressourcen, die vom XAML-Framework bereitgestellt werden, gibt es eine Reihe von Farbwerten, die von der Windows-Systempalette abgeleitet werden. Diese Farben sind nicht spezifisch für die Windows-Runtime- oder Windows-Apps. Viele der XAML-Pinselressourcen verbrauchen diese Farben jedoch, wenn das System ausgeführt wird (und die App ausgeführt wird) mit dem Design "HighContrast". Das XAML-Framework stellt diese systemweiten Farben als Schlüsselressourcen bereit. Die Schlüssel folgen dem Benennungsformat: SystemColor[name]Color.

Weitere Informationen zur Unterstützung von Kontrastdesigns finden Sie unter Kontrastdesigns.

Systemakzentfarbe

Zusätzlich zu den Designfarben für den Systemkontrast wird die Systemakzentfarbe als spezielle Farbressource mit dem Schlüssel SystemAccentColorbereitgestellt. Zur Laufzeit ruft diese Ressource die Farbe ab, die der Benutzer in den Windows-Personalisierungseinstellungen als Akzentfarbe angegeben hat.

Designabhängige Pinsel

Die in den vorherigen Abschnitten gezeigten Farbressourcen werden verwendet, um die Color-Eigenschaft von SolidColorBrush-Ressourcen in den Systemdesignressourcenwörterbüchern festzulegen. Sie verwenden die Pinselressourcen, um die Farbe auf XAML-Elemente anzuwenden.

Sehen wir uns an, wie der Farbwert für diesen Pinsel zur Laufzeit bestimmt wird. In den Ressourcenwörterbüchern "Hell" und "Dunkel" wird dieser Pinsel wie folgt definiert:

<SolidColorBrush x:Key="TextFillColorPrimaryBrush" Color="{StaticResource TextFillColorPrimary}"/>

Im Ressourcenverzeichnis "HighContrast" wird dieser Pinsel wie folgt definiert:

<SolidColorBrush x:Key="TextFillColorPrimaryBrush" Color="{ThemeResource SystemColorWindowTextColor}"/>

Wenn dieser Pinsel auf ein XAML-Element angewendet wird, wird die Farbe zur Laufzeit durch das aktuelle Design bestimmt, wie in dieser Tabelle dargestellt.

Die XAML-Typhierarchie

Die Datei themeresources.xaml definiert mehrere Ressourcen, die eine Formatvorlage definieren, die Sie auf Textcontainer in Ihrer Benutzeroberfläche anwenden können, insbesondere für TextBlock oder RichTextBlock. Dies sind nicht die impliziten Standardstile. Sie werden bereitgestellt, um Ihnen das Erstellen von XAML-UI-Definitionen zu erleichtern, die der Windows-Typhierarchie entsprechen, die in Richtlinien für Schriftarten dokumentiert ist.

Diese Formatvorlagen gelten für Textattribute, die Auf den gesamten Textcontainer angewendet werden sollen. Wenn Formatvorlagen nur auf Abschnitte des Texts angewendet werden sollen, legen Sie Attribute für die Textelemente im Container fest, z. B. auf einer Run in TextBlock.Inlines oder auf einem Absatz in RichTextBlock.Blocks.

Die Formatvorlagen sehen wie folgt aus, wenn sie auf einen TextBlock angewendet werden:

<TextBlock Text="Caption" Style="{StaticResource CaptionTextBlockStyle}"/>
<TextBlock Text="Body" Style="{StaticResource BodyTextBlockStyle}"/>
<TextBlock Text="Body Strong" Style="{StaticResource BodyStrongTextBlockStyle}"/>
<TextBlock Text="Body Large" Style="{StaticResource BodyLargeTextBlockStyle}"/>
<TextBlock Text="Subtitle" Style="{StaticResource SubtitleTextBlockStyle}"/>
<TextBlock Text="Title" Style="{StaticResource TitleTextBlockStyle}"/>
<TextBlock Text="Title Large" Style="{StaticResource TitleLargeTextBlockStyle}"/>
<TextBlock Text="Display" Style="{StaticResource DisplayTextBlockStyle}"/>

Anleitungen zur Verwendung der Windows-Typhierarchie in Ihrer App finden Sie unter Typografie in Windows-Apps.

Details zu den XAML-Stilen finden Sie unter WinUI auf GitHub:

• Caption TextBlockStyle
• Body TextBlockStyle
• Body Strong TextBlockStyle

• Subtitle TextBlockStyle
• Titel TextBlockStyle
• Titel Großer TextBlockStyle
• TextBlockStyle anzeigen

BaseRichTextBlockStyle

TargetType: RichTextBlock

Stellt die allgemeinen Eigenschaften für alle anderen RichTextBlock-Containerstile bereit.

<!-- Usage -->
<RichTextBlock Style="{StaticResource BaseRichTextBlockStyle}">
    <Paragraph>Rich text.</Paragraph>
</RichTextBlock>

<!-- Style definition -->
<Style x:Key="BaseRichTextBlockStyle" TargetType="RichTextBlock">
    <Setter Property="FontFamily" Value="Segoe UI"/>
    <Setter Property="FontWeight" Value="SemiBold"/>
    <Setter Property="FontSize" Value="14"/>
    <Setter Property="TextTrimming" Value="None"/>
    <Setter Property="TextWrapping" Value="Wrap"/>
    <Setter Property="LineStackingStrategy" Value="MaxHeight"/>
    <Setter Property="TextLineBounds" Value="Full"/>
    <Setter Property="OpticalMarginAlignment" Value="TrimSideBearings"/>
</Style>

BodyRichTextBlockStyle

<!-- Usage -->
<RichTextBlock Style="{StaticResource BodyRichTextBlockStyle}">
    <Paragraph>Rich text.</Paragraph>
</RichTextBlock>

<!-- Style definition -->
<Style x:Key="BodyRichTextBlockStyle" TargetType="RichTextBlock" BasedOn="{StaticResource BaseRichTextBlockStyle}">
    <Setter Property="FontWeight" Value="Normal"/>
</Style>

Hinweis: Die RichTextBlock-Formatvorlagen verfügen nicht über alle Texthierarchiestile, die TextBlock ausführt, hauptsächlich weil das blockbasierte Dokumentobjektmodell für RichTextBlock das Festlegen von Attributen für die einzelnen Textelemente erleichtert. Außerdem führt das Festlegen von "TextBlock.Text " mithilfe der XAML-Inhaltseigenschaft zu einer Situation, in der kein Textelement zum Formatieren vorhanden ist und Sie daher den Container formatieren müssen. Das ist kein Problem für RichTextBlock , da sich der Textinhalt immer in bestimmten Textelementen wie Paragraph befinden muss. Hier können Sie XAML-Formatvorlagen für Seitenüberschriften, Seitenunterüberschriften und ähnliche Texthierarchiedefinitionen anwenden.

Verschiedene benannte Formatvorlagen

Es gibt einen zusätzlichen Satz von Stildefinitionen mit Schlüsseln, die Sie anwenden können, um eine Schaltfläche anders als die implizite Standardformatvorlage zu formatieren.

NavigationBackButtonNormalStyle

TargetType: Button

Diese Formatvorlage bietet eine vollständige Vorlage für eine Schaltfläche , die die Navigationsschaltfläche "Zurück" für eine Navigations-App sein kann. Die Standardabmessungen sind 40 x 40 Pixel. Um die Formatierung anzupassen, können Sie entweder explizit die Eigenschaften "Height", "Width", "FontSize" und andere Eigenschaften auf der Schaltfläche festlegen oder eine abgeleitete Formatvorlage mithilfe von BasedOn erstellen.

Hier ist eine Schaltfläche mit der navigationBackButtonNormalStyle-Ressource , die darauf angewendet wurde.

<Button Style="{StaticResource NavigationBackButtonNormalStyle}" />

Dies sieht wie folgt aus:

NavigationBackButtonSmallStyle

TargetType: Button

Diese Formatvorlage bietet eine vollständige Vorlage für eine Schaltfläche , die die Navigationsschaltfläche "Zurück" für eine Navigations-App sein kann. Es ist ähnlich wie NavigationBackButtonNormalStyle, aber seine Abmessungen sind 30 x 30 Pixel.

Hier ist eine Schaltfläche , auf die die NavigationBackButtonSmallStyle-Ressource angewendet wurde.

<Button Style="{StaticResource NavigationBackButtonSmallStyle}" />

Problembehandlung bei Designressourcen

Wenn Sie die Richtlinien für die Verwendung von Designressourcen nicht befolgen, wird möglicherweise unerwartetes Verhalten im Zusammenhang mit Designs in Ihrer App angezeigt.

Wenn Sie z. B. ein Flyout mit hellem Design öffnen, ändern sich Teile Ihrer dunklen Design-App auch so, als wären sie im hellen Design vorhanden. Oder wenn Sie zu einer hellen Designseite navigieren und dann zurück navigieren, sieht die ursprüngliche seite mit dunklem Design (oder Teile davon) nun so aus, als ob sie sich im hellen Design befindet.

In der Regel treten diese Arten von Problemen auf, wenn Sie ein "Standard"-Design und ein "HighContrast"-Design bereitstellen, um Szenarien mit hohem Kontrast zu unterstützen, und verwenden Sie dann sowohl designs "Hell" als auch "Dunkel" in verschiedenen Teilen Ihrer App.

Betrachten Sie beispielsweise diese Designwörterbuchdefinition:

<!-- DO NOT USE. THIS XAML DEMONSTRATES AN ERROR. -->
<ResourceDictionary>
  <ResourceDictionary.ThemeDictionaries>
    <ResourceDictionary x:Key="Default">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource ControlFillColorDefault}"/>
    </ResourceDictionary>
    <ResourceDictionary x:Key="HighContrast">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource SystemColorButtonFaceColor}"/>
    </ResourceDictionary>
  </ResourceDictionary.ThemeDictionaries>
</ResourceDictionary>

Intuitiv sieht dies richtig aus. Sie möchten die Farbe ändern, auf myBrush die bei hohem Kontrast verwiesen wird, aber nicht im hohen Kontrast, verwenden Sie die {ThemeResource}-Markuperweiterung , um sicherzustellen, dass myBrush sie auf die richtige Farbe für Ihr Design verweist. Wenn Ihre App nie "FrameworkElement.RequestedTheme " für Elemente innerhalb der visuellen Struktur festgelegt hat, funktioniert dies in der Regel wie erwartet. In Ihrer App treten jedoch Probleme auf, sobald Sie beginnen, verschiedene Teile der visuellen Struktur neu zu entwerfen.

Das Problem tritt auf, da Pinsel freigegebene Ressourcen sind, im Gegensatz zu den meisten anderen XAML-Typen. Wenn Sie zwei Elemente in XAML-Unterstrukturen mit unterschiedlichen Designs haben, die auf dieselbe Pinselressource verweisen, werden änderungen an der freigegebenen Pinselressource in der anderen Unterstruktur widergespiegelt, da das Framework jede Unterstruktur durchläuft, um ihre {ThemeResource}-Markuperweiterungsausdrücke zu aktualisieren, änderungen an der freigegebenen Pinselressource in der anderen Unterstruktur widergespiegelt werden, was nicht Ihr beabsichtigtes Ergebnis ist.

Um dies zu beheben, ersetzen Sie das Wörterbuch "Standard" durch separate Designwörterbücher für designs "Light" und "Dark" zusätzlich zu "HighContrast":

<!-- DO NOT USE. THIS XAML DEMONSTRATES AN ERROR. -->
<ResourceDictionary>
  <ResourceDictionary.ThemeDictionaries>
    <ResourceDictionary x:Key="Light">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource ControlFillColorDefault}"/>
    </ResourceDictionary>
    <ResourceDictionary x:Key="Dark">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource ControlFillColorDefault}"/>
    </ResourceDictionary>
    <ResourceDictionary x:Key="HighContrast">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource SystemColorButtonFaceColor}"/>
    </ResourceDictionary>
  </ResourceDictionary.ThemeDictionaries>
</ResourceDictionary>

Es treten jedoch weiterhin Probleme auf, wenn auf eine dieser Ressourcen in geerbten Eigenschaften wie "Foreground" verwiesen wird. Ihre benutzerdefinierte Steuerelementvorlage kann die Vordergrundfarbe eines Elements mithilfe der {ThemeResource}-Markuperweiterung angeben, aber wenn das Framework den geerbten Wert an untergeordnete Elemente weitergibt, stellt sie einen direkten Verweis auf die Ressource bereit, die vom {ThemeResource}-Markuperweiterungsausdruck aufgelöst wurde. Dies verursacht Probleme, wenn das Framework Designänderungen verarbeitet, während es die visuelle Struktur Ihres Steuerelements durchläuft. Er wertet den {ThemeResource}-Markuperweiterungsausdruck erneut aus, um eine neue Pinselressource zu erhalten, aber diesen Verweis noch nicht an die untergeordneten Elemente des Steuerelements weiterleitet. Dies geschieht später, z. B. während des nächsten Messdurchlaufs.

Daher führt das Framework nach dem Navigieren der visuellen Steuerelementstruktur als Reaktion auf eine Designänderung die untergeordneten Elemente durch und aktualisiert alle für sie festgelegten {ThemeResource}-Markuperweiterungsausdrücke oder für Objekte, die für ihre Eigenschaften festgelegt sind. Hier tritt das Problem auf; Das Framework führt die Pinselressource durch und da es seine Farbe mithilfe einer {ThemeResource}-Markuperweiterung angibt, wird sie erneut ausgewertet.

An diesem Punkt scheint das Framework Ihr Designwörterbuch verunreinigt zu haben, da es jetzt eine Ressource aus einem Wörterbuch enthält, das seine Farbe aus einem anderen Wörterbuch festgelegt hat.

Um dieses Problem zu beheben, verwenden Sie die {StaticResource}-Markuperweiterung anstelle der {ThemeResource}-Markuperweiterung. Mit den angewendeten Richtlinien sehen die Designwörterbücher wie folgt aus:

<ResourceDictionary>
  <ResourceDictionary.ThemeDictionaries>
    <ResourceDictionary x:Key="Light">
      <SolidColorBrush x:Key="myBrush" Color="{StaticResource ControlFillColorDefault}"/>
    </ResourceDictionary>
    <ResourceDictionary x:Key="Dark">
      <SolidColorBrush x:Key="myBrush" Color="{StaticResource ControlFillColorDefault}"/>
    </ResourceDictionary>
    <ResourceDictionary x:Key="HighContrast">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource SystemColorButtonFaceColor}"/>
    </ResourceDictionary>
  </ResourceDictionary.ThemeDictionaries>
</ResourceDictionary>

Beachten Sie, dass die {ThemeResource}-Markuperweiterung weiterhin im Wörterbuch "HighContrast" anstelle der {StaticResource}-Markuperweiterung verwendet wird. Diese Situation fällt unter die zuvor in den Richtlinien angeführte Ausnahme. Die meisten Pinselwerte, die für das Design "HighContrast" verwendet werden, verwenden Farbauswahlen, die global vom System gesteuert werden, aber XAML als speziell benannte Ressource verfügbar gemacht werden (die mit dem Präfix 'SystemColor' im Namen). Das System ermöglicht es dem Benutzer, die spezifischen Farben festzulegen, die für seine Kontrastdesigneinstellungen über das Center für erleichterte Bedienung verwendet werden sollen. Diese Farbauswahl wird auf die speziell benannten Ressourcen angewendet. Das XAML-Framework verwendet dasselbe Designänderungsereignis, um diese Pinsel auch zu aktualisieren, wenn erkannt wird, dass sie auf Systemebene geändert wurden. Aus diesem Grund wird hier die {ThemeResource}-Markuperweiterung verwendet.