Partager via

Extension de balisage {ThemeResource}

  • Article

Fournit une valeur pour n’importe quel attribut XAML en évaluant une référence à une ressource, avec une logique système supplémentaire qui récupère différentes ressources en fonction du thème actuellement actif. Comme pour l’extension de balisage {StaticResource}, les ressources sont définies dans un ResourceDictionary et une utilisation de ThemeResource fait référence à la clé de cette ressource dans ResourceDictionary.

Utilisation des attributs XAML

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

Valeurs XAML

Terme Description
key Clé pour la ressource demandée. Cette clé est initialement affectée par ResourceDictionary. Une clé de ressource peut être n’importe quelle chaîne définie dans la grammaire XamlName.

Notes

Un ThemeResource est une technique permettant d’obtenir des valeurs pour un attribut XAML qui sont définis ailleurs dans un dictionnaire de ressources XAML. L’extension de balisage sert le même objectif de base que l’extension de balisage {StaticResource}. La différence de comportement par rapport à l’extension de balisage {StaticResource} est qu’une référence ThemeResource peut utiliser dynamiquement différents dictionnaires comme emplacement de recherche principal, selon le thème actuellement utilisé par le système.

Au démarrage de l’application, toute référence de ressource effectuée par une référence ThemeResource est évaluée en fonction du thème utilisé au démarrage. Toutefois, si l’utilisateur modifie par la suite le thème actif au moment de l’exécution, le système réévalue chaque référence ThemeResource , récupère une ressource spécifique au thème qui peut être différente et réexécute l’application avec de nouvelles valeurs de ressource à tous les emplacements appropriés dans l’arborescence visuelle. StaticResource est déterminé au démarrage de l’application/heure de chargement XAML et ne sera pas réévalué au moment de l’exécution. (Il existe d’autres techniques telles que les états visuels qui rechargent le code XAML dynamiquement, mais ces techniques fonctionnent à un niveau plus élevé que l’évaluation des ressources de base activée par Extension de balisage {StaticResource}).

ThemeResource prend un argument, qui spécifie la clé de la ressource demandée. Une clé de ressource est toujours une chaîne en XAML Windows Runtime. Pour plus d’informations sur la façon dont la clé de ressource est initialement spécifiée, consultez l’attribut x :Key.

Pour plus d’informations sur la définition des ressources et l’utilisation correcte d’un ResourceDictionary, y compris l’exemple de code, consultez les références de ressources ResourceDictionary et XAML.

Important comme avec StaticResource, un ThemeResource ne doit pas tenter d’effectuer une référence avant à une ressource définie lexicalement plus loin dans le fichier XAML. La tentative de ce faire n’est pas prise en charge. Même si la référence vers l’avant n’échoue pas, essayez de faire en sorte qu’une pénalité de performance soit appliquée. Pour obtenir de meilleurs résultats, ajustez la composition de vos dictionnaires de ressources afin que les références vers l’avant soient évitées.

Toute tentative de spécification d’un ThemeResource à une clé qui ne peut pas résoudre lève une exception d’analyse XAML au moment de l’exécution. Les outils de conception peuvent également proposer des avertissements ou des erreurs.

Dans l’implémentation du processeur XAML Windows Runtime, il n’existe aucune représentation de classe de stockage pour ThemeResource. L’équivalent le plus proche dans le code consiste à utiliser l’API de collection d’un ResourceDictionary, par exemple en appelant Contains ou *TryGetValue.

ThemeResource est une extension de balisage. Les extensions de balisage sont généralement implémentées pour éviter que les valeurs d’attribut ne soient autre chose que des valeurs littérales ou des noms de gestionnaire et lorsque l’exigence dépasse le cadre de la définition de convertisseurs de type sur certains types ou propriétés. Toutes les extensions de balisage en XAML utilisent les caractères « { » et « } » dans leur syntaxe d’attribut, c’est-à-dire la convention par laquelle un processeur XAML reconnaît qu’une extension de balisage doit traiter l’attribut.

Quand et comment utiliser {ThemeResource} plutôt que {StaticResource}

Les règles par lesquelles un ThemeResource se résout en un élément d’un dictionnaire de ressources sont généralement identiques à StaticResource. Une recherche ThemeResource peut s’étendre aux fichiers ResourceDictionary référencés dans une collection ThemeDictionaries, mais un StaticResource peut également le faire. La différence est qu’un ThemeResource peut réévaluer au moment de l’exécution et qu’un StaticResource ne peut pas.

L’ensemble de clés dans chaque dictionnaire de thèmes doit fournir le même ensemble de ressources à clé, quel que soit le thème actif. Si une ressource à clé donnée existe dans le dictionnaire de thème HighContrast , une autre ressource portant ce nom doit également exister dans Light et Default. Si ce n’est pas vrai, la recherche de ressources peut échouer lorsque l’utilisateur change de thème et que votre application ne s’affiche pas correctement. Il est possible qu’un dictionnaire de thème puisse contenir des ressources clé qui ne sont référencées qu’à partir de la même étendue pour fournir des sous-valeurs ; ils n’ont pas besoin d’être équivalents dans tous les thèmes.

En général, vous devez placer des ressources dans des dictionnaires de thèmes et faire des références à ces ressources à l’aide de ThemeResource uniquement lorsque ces valeurs peuvent changer entre les thèmes ou sont prises en charge par les valeurs qui changent. Cela convient pour ces types de ressources :

  • Pinceaux, en particulier pour SolidColorBrush. Celles-ci constituent environ 80 % des utilisations themeResource dans les modèles de contrôle XAML par défaut (generic.xaml).
  • Valeurs de pixels pour les bordures, les décalages, la marge et le remplissage, et ainsi de suite.
  • Propriétés de police telles que FontFamily ou FontSize.
  • Effectuez des modèles pour un nombre limité de contrôles généralement mis en forme par le système et utilisés pour la présentation dynamique, comme GridViewItem et ListViewItem.
  • Styles d’affichage de texte (généralement pour modifier la couleur de police, l’arrière-plan et éventuellement la taille).

Windows Runtime fournit un ensemble de ressources spécifiquement destinées à être référencées par ThemeResource. Tous répertoriés dans le fichier XAML themeresources.xaml, qui est disponible dans le dossier include/winrt/xaml/design dans le cadre du Kit de développement logiciel (SDK) Windows. Pour obtenir de la documentation sur les pinceaux de thème et les styles supplémentaires définis dans themeresources.xaml, consultez les ressources de thème XAML. Les pinceaux sont documentés dans un tableau qui vous indique quelle valeur de couleur chaque pinceau a pour chacun des trois thèmes actifs possibles.

Les définitions XAML des états visuels dans un modèle de contrôle doivent utiliser des références ThemeResource chaque fois qu’il existe une ressource sous-jacente susceptible de changer en raison d’une modification de thème. Une modification de thème système n’entraîne généralement pas de changement d’état visuel. Les ressources doivent utiliser des références ThemeResource dans ce cas afin que les valeurs puissent être réévaluées pour l’état visuel toujours actif. Par exemple, si vous avez un état visuel qui modifie une couleur de pinceau d’une partie d’interface utilisateur particulière et l’une de ses propriétés, et que la couleur de pinceau est différente par thème, vous devez utiliser une référence ThemeResource pour fournir la valeur de cette propriété dans le modèle par défaut et toute modification de l’état visuel de ce modèle par défaut.

Les utilisations de ThemeResource peuvent être vues dans une série de valeurs dépendantes. Par exemple, une valeur Color utilisée par un SolidColorBrush qui est également une ressource clé peut utiliser une référence ThemeResource. Toutefois, toutes les propriétés d’interface utilisateur qui utilisent la ressource SolidColorBrush keyed utilisent également une référence ThemeResource, de sorte qu’il s’agit spécifiquement de chaque propriété de type Brush qui permet une modification de valeur dynamique lorsque le thème change.

Notez{ThemeResource} que l’évaluation des ressources au moment de l’exécution sur le basculement de thème est prise en charge dans XAML Windows 8.1, mais pas en XAML pour les applications ciblant Windows 8.

Ressources système

Certaines ressources de thème référencent les valeurs de ressources système en tant que sous-valeur sous-jacente. Une ressource système est une valeur de ressource spéciale qui n’est trouvée dans aucun dictionnaire de ressources XAML. Ces valeurs s’appuient sur le comportement dans la prise en charge XAML de Windows Runtime pour transférer les valeurs du système lui-même et les représenter sous la forme qu’une ressource XAML peut référencer. Par exemple, il existe une ressource système nommée « SystemColorButtonFaceColor » qui représente une couleur RVB. Cette couleur provient des aspects des couleurs système et des thèmes qui ne sont pas uniquement spécifiques aux applications Windows Runtime et Windows Runtime.

Les ressources système sont souvent les valeurs sous-jacentes d’un thème à contraste élevé. L’utilisateur contrôle les choix de couleur de son thème à contraste élevé et l’utilisateur effectue ces choix à l’aide de fonctionnalités système qui ne sont pas non plus spécifiques aux applications Windows Runtime. En référençant les ressources système en tant que références ThemeResource , le comportement par défaut des thèmes à contraste élevé pour les applications Windows Runtime peut utiliser ces valeurs spécifiques au thème contrôlées par l’utilisateur et exposées par le système. En outre, les références sont désormais marquées pour une nouvelle évaluation si le système détecte une modification de thème d’exécution.

Exemple d’utilisation de {ThemeResource}

Voici un exemple de code XAML extrait des fichiers generic.xaml par défaut et themeresources.xaml pour illustrer l’utilisation de ThemeResource. Nous allons examiner un seul modèle (le bouton par défaut) et comment deux propriétés sont déclarées (arrière-plan et premier plan) pour être réactives aux modifications de thème.

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

Ici, les propriétés prennent une valeur Brush et la référence aux ressources SolidColorBrush nommées ButtonBackgroundThemeBrush et ButtonForegroundThemeBrush sont effectuées à l’aide de ThemeResource.

Ces mêmes propriétés sont également ajustées par certains des états visuels d’un bouton. Notamment, la couleur d’arrière-plan change lorsqu’un bouton est cliqué. Ici aussi, les animations d’arrière-plan et de premier plan dans le storyboard d’état visuel utilisent des objets DiscreteObjectKeyFrame et des références aux pinceaux avec ThemeResource comme valeur d’image clé.

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

Chacun de ces pinceaux est défini précédemment dans generic.xaml : ils doivent être définis avant les modèles qui les utilisent pour éviter les références de transfert XAML. Voici ces définitions, pour le dictionnaire de thème « Par défaut ».

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

Ensuite, chacun des autres dictionnaires de thème a également ces pinceaux définis, par exemple :

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

Ici, la valeur Color est une autre référence ThemeResource à une ressource système. Si vous référencez une ressource système et que vous souhaitez qu’elle change en réponse à une modification de thème, vous devez utiliser ThemeResource pour faire la référence.

Comportement de Windows 8

Windows 8 n’a pas pris en charge l’extension de balisage ThemeResource , elle est disponible à partir de Windows 8.1. En outre, Windows 8 ne prenait pas en charge le basculement dynamique des ressources liées au thème pour une application Windows Runtime. L’application devait être redémarrée pour récupérer la modification du thème pour les modèles et styles XAML. Ce n’est pas une bonne expérience utilisateur. Les applications sont donc fortement encouragées à recompiler et cibler Windows 8.1 afin qu’elles puissent utiliser des styles avec des utilisations ThemeResource et changer dynamiquement de thèmes lorsque l’utilisateur le fait. Les applications compilées pour Windows 8, mais exécutées sur Windows 8.1 continuent d’utiliser le comportement de Windows 8.

Prise en charge des outils au moment du design pour l’extension de balisage {ThemeResource}

Microsoft Visual Studio 2013 peut inclure des valeurs clés possibles dans les listes déroulantes Microsoft IntelliSense lorsque vous utilisez l’extension de balisage {ThemeResource} dans une page XAML. Par exemple, dès que vous tapez « {ThemeResource », toutes les clés de ressource des ressources des ressources de thème XAML sont affichées.

Une fois qu’une clé de ressource existe dans le cadre de l’utilisation de {ThemeResource} , la fonctionnalité Go To Definition (F12) peut résoudre cette ressource et vous montrer le fichier generic.xaml pour le temps de conception, où la ressource de thème est définie. Étant donné que les ressources de thème sont définies plusieurs fois (par thème) Go To Definition vous amène à la première définition trouvée dans le fichier, qui est la définition par défaut. Si vous souhaitez que les autres définitions, vous pouvez rechercher le nom de clé dans le fichier et rechercher les définitions des autres thèmes.