Ressources de thème XAML

Les ressources de thème en XAML sont un ensemble de ressources qui appliquent différentes valeurs selon le thème système actif. Il existe 3 thèmes pris en charge par l’infrastructure XAML : « Light », « Dark » et « HighContrast ».

Conditions préalables : cette rubrique suppose que vous avez lu les références de ressources ResourceDictionary et XAML.

Ressources de thème v. ressources statiques

Il existe deux extensions de balisage XAML qui peuvent référencer une ressource XAML à partir d’un dictionnaire de ressources XAML existant : l’extension de balisage {StaticResource} et l’extension de balisage {ThemeResource}.

L’évaluation d’une extension de balisage {ThemeResource} se produit lorsque l’application charge et par la suite chaque fois que le thème change au moment de l’exécution. Il s’agit généralement du résultat de la modification des paramètres de l’appareil par l’utilisateur ou d’une modification programmatique au sein de l’application qui modifie son thème actuel.

En revanche, une extension de balisage {StaticResource} est évaluée uniquement lorsque le code XAML est chargé pour la première fois par l’application. Elle ne se met pas à jour. Il est similaire à une recherche et à un remplacement dans votre code XAML par la valeur d’exécution réelle au lancement de l’application.

Ressources de thème dans la structure du dictionnaire de ressources

Chaque ressource de thème fait partie du fichier XAML themeresources.xaml. À des fins de conception, themeresources.xaml est disponible dans le dossier \(Program Files)\Windows Kits\10\DesignTime\CommonConfiguration\Neutral\UAP\<SDK version>\Generic à partir d’une installation du Kit de développement logiciel (SDK) Windows. Les dictionnaires de ressources dans themeresources.xaml sont également reproduits dans generic.xaml dans le même répertoire.

Windows Runtime n’utilise pas ces fichiers physiques pour la recherche du runtime. C’est pourquoi ils se trouvent spécifiquement dans un dossier DesignTime et ne sont pas copiés dans des applications par défaut. Au lieu de cela, ces dictionnaires de ressources existent en mémoire dans le cadre de Windows Runtime lui-même, et les références de ressources XAML de votre application aux ressources de thème (ou ressources système) s’y résolvent au moment de l’exécution.

Instructions pour les ressources de thème personnalisées

Suivez ces instructions lorsque vous définissez et consommez vos propres ressources de thème personnalisées :

• Spécifiez les dictionnaires de thème pour « Light » et « Dark » en plus de votre dictionnaire « HighContrast ». Bien que vous puissiez créer un ResourceDictionary avec « Default » comme clé, il est préférable d’être explicite et d’utiliser plutôt « Light », « Dark » et « HighContrast ».

• Utilisez l’extension de balisage {ThemeResource} dans : styles, setters, modèles de contrôle, ensembles de propriétés et animations.

• N’utilisez pas l’extension de balisage {ThemeResource} dans vos définitions de ressources à l’intérieur de vos ThemeDictionaries. Utilisez plutôt l’extension de balisage {StaticResource} .

  EXCEPTION : vous pouvez utiliser l’extension de balisage {ThemeResource} pour référencer les ressources indépendantes du thème de l’application dans vos ThemeDictionaries. Par exemple, ces ressources sont des ressources de couleur d’accentuation telles que SystemAccentColordes ressources de couleur système, qui sont généralement précédées de « SystemColor » comme SystemColorButtonFaceColor.

Rampe de couleur XAML et pinceaux dépendant du thème

L’ensemble combiné de couleurs pour les thèmes « Light », « Dark » et « HighContrast » constituent la rampe de couleurs Windows en XAML. Que vous souhaitiez modifier les thèmes système ou appliquer un thème à vos propres éléments XAML, il est important de comprendre comment les ressources de couleur sont structurées.

Pour plus d’informations sur l’application de couleur dans votre application Windows, consultez Color in Windows apps.

Couleurs de thème clair et foncé

L’infrastructure XAML fournit un ensemble de ressources color nommées avec des valeurs adaptées aux thèmes « Clair » et « Sombre ». Pour WinUI 2, les ressources de thème sont définies dans le fichier Xaml des ressources de thème communes. Les noms de couleurs sont très descriptifs de leur utilisation prévue et il existe une ressource SolidColorBrush correspondante pour chaque ressource Color.

L’application Galerie WinUI 3 inclut des exemples interactifs de la plupart des contrôles, fonctionnalités et fonctionnalités WinUI 3. Obtenir l’application à partir du Microsoft Store ou obtenir le code source sur GitHub

Couleurs de thème de contraste système Windows

Outre l’ensemble de ressources fournies par l’infrastructure XAML, il existe un ensemble de valeurs de couleur dérivées de la palette système Windows. Ces couleurs ne sont pas spécifiques aux applications Windows Runtime ou Windows. Toutefois, la plupart des ressources de pinceau XAML consomment ces couleurs lorsque le système fonctionne (et que l’application est en cours d’exécution) à l’aide du thème « HighContrast ». L’infrastructure XAML fournit ces couleurs à l’échelle du système en tant que ressources clés. Les clés suivent le format d’affectation de noms : SystemColor[name]Color.

Pour plus d’informations sur la prise en charge des thèmes de contraste, consultez Thèmes de contraste.

Couleur d’accentuation système

En plus des couleurs de thème de contraste système, la couleur d’accentuation système est fournie en tant que ressource de couleur spéciale à l’aide de la clé SystemAccentColor. Au moment de l’exécution, cette ressource obtient la couleur que l’utilisateur a spécifiée comme couleur d’accentuation dans les paramètres de personnalisation Windows.

Pinceaux dépendants du thème

Les ressources de couleur affichées dans les sections précédentes sont utilisées pour définir la propriété Color des ressources SolidColorBrush dans les dictionnaires de ressources de thème système. Vous utilisez les ressources de pinceau pour appliquer la couleur aux éléments XAML.

Examinons comment la valeur de couleur de ce pinceau est déterminée au moment de l’exécution. Dans les dictionnaires de ressources « Clair » et « Sombre », ce pinceau est défini comme suit :

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

Dans le dictionnaire de ressources « HighContrast », ce pinceau est défini comme suit :

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

Lorsque ce pinceau est appliqué à un élément XAML, sa couleur est déterminée au moment de l’exécution par le thème actuel, comme indiqué dans ce tableau.

Rampe de type XAML

Le fichier themeresources.xaml définit plusieurs ressources qui définissent un style que vous pouvez appliquer aux conteneurs de texte dans votre interface utilisateur, en particulier pour TextBlock ou RichTextBlock. Ce ne sont pas les styles implicites par défaut. Ils sont fournis pour faciliter la création de définitions d’interface utilisateur XAML qui correspondent à la rampe de type Windows documentée dans Instructions pour les polices.

Ces styles concernent les attributs de texte que vous souhaitez appliquer au conteneur de texte entier. Si vous souhaitez appliquer des styles uniquement à des sections du texte, définissez des attributs sur les éléments de texte du conteneur, tels que sur une exécution dans TextBlock.Inlines ou sur un paragraphe dans RichTextBlock.Blocks.

Les styles ressemblent à ceci lorsqu’ils sont appliqués à un TextBlock :

<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}"/>

Pour obtenir des conseils sur l’utilisation de la rampe de type Windows dans votre application, consultez Typographie dans les applications Windows.

Pour plus d’informations sur les styles XAML, consultez WinUI sur GitHub :

• Caption TextBlockStyle
• Body TextBlockStyle
• Body Strong TextBlockStyle

• TextBlockStyle sous-titre
• Title TextBlockStyle
• Title Large TextBlockStyle
• Afficher TextBlockStyle

BaseRichTextBlockStyle

TargetType : RichTextBlock

Fournit les propriétés communes pour tous les autres styles de conteneur RichTextBlock .

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

Remarque : Les styles RichTextBlock n’ont pas tous les styles de rampe de texte que TextBlock effectue, principalement parce que le modèle objet de document basé sur bloc pour RichTextBlock facilite la définition d’attributs sur les éléments de texte individuels. En outre, la définition de TextBlock.Text à l’aide de la propriété de contenu XAML introduit une situation où il n’y a pas d’élément de texte à styler et donc vous devrez styler le conteneur. Ce n’est pas un problème pour RichTextBlock , car son contenu de texte doit toujours se trouver dans des éléments de texte spécifiques tels que Paragraph, c’est-à-dire que vous pouvez appliquer des styles XAML pour l’en-tête de page, le sous-tête de page et les définitions de rampe de texte similaires.

Styles nommés divers

Il existe un ensemble supplémentaire de définitions de style à touches que vous pouvez appliquer au style d’un bouton différemment de son style implicite par défaut.

NavigationBackButtonNormalStyle

TargetType : bouton

Ce style fournit un modèle complet pour un bouton qui peut être le bouton précédent de navigation d’une application de navigation. Les dimensions par défaut sont de 40 x 40 pixels. Pour personnaliser le style, vous pouvez définir explicitement la hauteur, la largeur, la police et d’autres propriétés sur votre bouton ou créer un style dérivé à l’aide de BasedOn.

Voici un bouton avec la ressource NavigationBackButtonNormalStyle qui lui est appliquée.

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

Elle se présente comme suit :

NavigationBackButtonSmallStyle

TargetType : bouton

Ce style fournit un modèle complet pour un bouton qui peut être le bouton précédent de navigation d’une application de navigation. Il est similaire à NavigationBackButtonNormalStyle, mais ses dimensions sont de 30 x 30 pixels.

Voici un bouton avec la ressource NavigationBackButtonSmallStyle qui lui est appliquée.

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

Résolution des problèmes liés aux ressources de thème

Si vous ne suivez pas les instructions relatives à l’utilisation des ressources de thème, vous pouvez voir un comportement inattendu lié aux thèmes de votre application.

Par exemple, lorsque vous ouvrez un menu volant à thème clair, les parties de votre application en thème foncé changent également comme si elles étaient dans le thème clair. Ou si vous accédez à une page à thème clair, puis revenez, la page à thème foncé d’origine (ou les parties de celui-ci) ressemble maintenant comme si elle se trouve dans le thème clair.

En règle générale, ces types de problèmes se produisent lorsque vous fournissez un thème « Par défaut » et un thème « HighContrast » pour prendre en charge les scénarios à contraste élevé, puis utilisez les thèmes « Clair » et « Sombre » dans différentes parties de votre application.

Par exemple, considérez cette définition de dictionnaire de thème :

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

Intuitivement, cela semble correct. Vous souhaitez modifier la couleur pointée par myBrush le moment où elle est à contraste élevé, mais quand elle n’est pas en contraste élevé, vous vous appuyez sur l’extension de balisage {ThemeResource} pour vous assurer que myBrush cela pointe vers la couleur appropriée pour votre thème. Si votre application n’a jamais défini FrameworkElement.RequestedTheme sur les éléments de son arborescence visuelle, cela fonctionnera généralement comme prévu. Toutefois, vous rencontrez des problèmes dans votre application dès que vous commencez à recréer différentes parties de votre arborescence visuelle.

Le problème se produit parce que les pinceaux sont des ressources partagées, contrairement à la plupart des autres types XAML. Si vous avez 2 éléments dans les sous-arborescences XAML avec différents thèmes qui référencent la même ressource de pinceau, alors que l’infrastructure guide chaque sous-arborescence pour mettre à jour ses expressions d’extension de balisage {ThemeResource} , les modifications apportées à la ressource de pinceau partagé sont reflétées dans l’autre sous-arborescence, ce qui n’est pas votre résultat prévu.

Pour résoudre ce problème, remplacez le dictionnaire « Default » par des dictionnaires de thèmes distincts pour les thèmes « Light » et « Dark » en plus de « 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>

Toutefois, des problèmes se produisent toujours si l’une de ces ressources est référencée dans des propriétés héritées comme foreground. Votre modèle de contrôle personnalisé peut spécifier la couleur de premier plan d’un élément à l’aide de l’extension de balisage {ThemeResource}, mais lorsque l’infrastructure propage la valeur héritée aux éléments enfants, elle fournit une référence directe à la ressource résolue par l’expression d’extension de balisage {ThemeResource}. Cela provoque des problèmes lorsque l’infrastructure traite les modifications de thème au fur et à mesure qu’elle guide l’arborescence visuelle de votre contrôle. Il réévalue l’expression d’extension de balisage {ThemeResource} pour obtenir une nouvelle ressource de pinceau, mais ne propage pas encore cette référence aux enfants de votre contrôle ; cela se produit ultérieurement, par exemple lors de la passe de mesure suivante.

Par conséquent, après avoir parcouru l’arborescence visuelle de contrôle en réponse à une modification de thème, l’infrastructure guide les enfants et met à jour les expressions d’extension de balisage {ThemeResource} définies sur elles ou sur les objets définis sur leurs propriétés. C’est là que le problème se produit ; l’infrastructure guide la ressource de pinceau et, car elle spécifie sa couleur à l’aide d’une extension de balisage {ThemeResource}, elle est réévaluée.

À ce stade, le framework semble avoir pollué votre dictionnaire de thème, car il a maintenant une ressource d’un dictionnaire qui a sa couleur définie à partir d’un autre dictionnaire.

Pour résoudre ce problème, utilisez l’extension de balisage {StaticResource} au lieu de l’extension de balisage {ThemeResource}. Avec les instructions appliquées, les dictionnaires de thèmes ressemblent à ceci :

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

Notez que l’extension de balisage {ThemeResource} est toujours utilisée dans le dictionnaire « HighContrast » au lieu de l’extension de balisage {StaticResource}. Cette situation relève de l’exception donnée précédemment dans les directives. La plupart des valeurs de pinceau utilisées pour le thème « HighContrast » utilisent des choix de couleurs qui sont globalement contrôlés par le système, mais exposés au code XAML en tant que ressource spécialement nommée (celles précédées de « SystemColor » dans le nom). Le système permet à l’utilisateur de définir les couleurs spécifiques qui doivent être utilisées pour leurs paramètres de thème de contraste via le Centre d’authentification facile d’accès. Ces choix de couleur sont appliqués aux ressources spécialement nommées. L’infrastructure XAML utilise le même événement de modification de thème pour mettre à jour ces pinceaux lorsqu’il détecte qu’ils ont changé au niveau du système. C’est pourquoi l’extension de balisage {ThemeResource} est utilisée ici.