Personnaliser vos ressources pour la langue, l’échelle, le contraste élevé et d’autres qualificateurs

  • Article

Cette rubrique explique le concept général des qualificateurs de ressource, leur utilisation et le rôle de chacun des noms de qualificateur. Consultez ResourceContext.QualifierValues pour obtenir une table de référence de toutes les valeurs de qualificateur possibles.

Votre application peut charger des ressources et des ressources adaptées à des contextes d’exécution tels que la langue d’affichage, le contraste élevé, le facteur d’échelle d’affichage et bien d’autres. La façon dont vous procédez consiste à nommer les dossiers ou fichiers de vos ressources pour qu’ils correspondent aux noms de qualificateurs et aux valeurs de qualificateur qui correspondent à ces contextes. Par exemple, vous souhaiterez peut-être que votre application charge un autre ensemble de ressources d’image en mode de contraste élevé.

Pour plus d’informations sur la proposition de valeur de la localisation de votre application, consultez Internationalisation et localisation.

Nom du qualificateur, valeur du qualificateur et qualificateur

Un nom de qualificateur est une clé qui correspond à un ensemble de valeurs de qualificateur. Voici le nom du qualificateur et les valeurs de qualificateur pour le contraste.

Context Nom du qualificateur Valeurs de qualificateur
Paramètre de contraste élevé élevé standard, élevé, noir, blanc

Vous combinez un nom de qualificateur avec une valeur de qualificateur pour former un qualificateur. <qualifier name>-<qualifier value> est le format d’un qualificateur. contrast-standard est un exemple de qualificateur.

Ainsi, pour un contraste élevé, l’ensemble des qualificateurs est contrast-standard, contrast-high, contrast-blacket contrast-white. Les noms des qualificateurs et les valeurs des qualificateurs ne respectent pas la casse. Par exemple, contrast-standard et Contrast-Standard sont le même qualificateur.

Utiliser des qualificateurs dans les noms de dossiers

Voici un exemple d’utilisation de qualificateurs pour nommer les dossiers qui contiennent des fichiers de ressources. Utilisez des qualificateurs dans les noms de dossiers si vous avez plusieurs fichiers de ressources par qualificateur. De cette façon, vous définissez le qualificateur une fois au niveau du dossier, et le qualificateur s’applique à tout ce qui se trouve dans le dossier.

\Assets\Images\contrast-standard\<logo.png, and other image files>
\Assets\Images\contrast-high\<logo.png, and other image files>
\Assets\Images\contrast-black\<logo.png, and other image files>
\Assets\Images\contrast-white\<logo.png, and other image files>

Si vous nommez vos dossiers comme dans l’exemple ci-dessus, votre application utilise le paramètre de contraste élevé pour charger les fichiers de ressources à partir du dossier nommé pour le qualificateur approprié. Par conséquent, si le paramètre est Noir à contraste élevé, les fichiers de ressources dans le \Assets\Images\contrast-black dossier sont chargés. Si le paramètre est None (autrement dit, l’ordinateur n’est pas en mode contraste élevé), les fichiers de ressources dans le \Assets\Images\contrast-standard dossier sont chargés.

Utiliser des qualificateurs dans les noms de fichiers

Au lieu de créer et de nommer des dossiers, vous pouvez utiliser un qualificateur pour nommer les fichiers de ressources eux-mêmes. Vous préférerez peut-être le faire si vous n’avez qu’un seul fichier de ressources par qualificateur. Voici un exemple.

\Assets\Images\logo.contrast-standard.png
\Assets\Images\logo.contrast-high.png
\Assets\Images\logo.contrast-black.png
\Assets\Images\logo.contrast-white.png

Le fichier dont le nom contient le qualificateur le plus approprié pour le paramètre est celui qui est chargé. Cette logique de correspondance fonctionne de la même façon pour les noms de fichiers que pour les noms de dossiers.

Référencer une ressource de chaîne ou d’image par nom

Consultez Référencer un identificateur de ressource de chaîne à partir du balisage XAML, Faire référence à un identificateur de ressource de chaîne à partir du code et Référencer une image ou une autre ressource à partir du balisage et du code XAML.

Correspondances de qualificateurs réels et neutres

Vous n’avez pas besoin de fournir un fichier de ressources pour chaque valeur de qualificateur. Par exemple, si vous constatez que vous n’avez besoin que d’une seule ressource visuelle pour un contraste élevé et d’une autre pour le contraste standard, vous pouvez les nommer comme suit.

\Assets\Images\logo.contrast-high.png
\Assets\Images\logo.png

Le premier nom de fichier contient le contrast-high qualificateur. Ce qualificateur est une correspondance réelle pour tout paramètre de contraste élevé lorsque le contraste élevé est activé. En d’autres termes, c’est une correspondance proche donc c’est préférable. Une correspondance réelle ne peut se produire que si le qualificateur contient une valeur réelle , comme celle-ci. Dans ce cas, high est une valeur réelle pour contrast.

Le fichier nommé logo.png n’a aucun qualificateur de contraste. L’absence d’un qualificateur est une valeur neutre . Si aucune correspondance préférée n’est trouvée, la valeur neutre sert de correspondance de secours. Dans cet exemple, si le contraste élevé est désactivé, il n’y a aucune correspondance réelle. La correspondance neutre est la meilleure correspondance qui puisse être trouvée, de sorte que la ressource logo.png est chargée.

Si vous changez le nom de logo.png en logo.contrast-standard.png, le nom de fichier contient une valeur qualificateur réelle. Avec un contraste élevé désactivé, il y aurait une correspondance réelle avec logo.contrast-standard.png, et c’est le fichier de ressources qui serait chargé. Ainsi, les mêmes fichiers seraient chargés, dans les mêmes conditions, mais en raison de correspondances différentes.

Si vous n’avez besoin que d’un seul ensemble de ressources pour un contraste élevé et d’un jeu pour le contraste standard, vous pouvez utiliser des noms de dossiers au lieu de noms de fichiers. Dans ce cas, l’omission complète du nom du dossier vous donne la correspondance neutre.

\Assets\Images\contrast-high\<logo.png, and other images to load when high contrast theme is not None>
\Assets\Images\<logo.png, and other images to load when high contrast theme is None>

Pour plus d’informations sur le fonctionnement de la correspondance des qualificateurs, consultez Resource Management System.

Qualificateurs multiples

Vous pouvez combiner des qualificateurs dans les noms de dossiers et de fichiers. Par exemple, vous pouvez souhaiter que votre application charge des ressources d’image lorsque le mode contraste élevé est activé et que le facteur d’échelle d’affichage est de 400. Pour ce faire, vous pouvez utiliser des dossiers imbriqués.

\Assets\Images\contrast-high\scale-400\<logo.png, and other image files>

Pour logo.png et les autres fichiers à charger, les paramètres doivent correspondre aux deux qualificateurs.

Une autre option consiste à combiner plusieurs qualificateurs dans un nom de dossier.

\Assets\Images\contrast-high_scale-400\<logo.png, and other image files>

Dans un nom de dossier, vous combinez plusieurs qualificateurs séparés par un trait de soulignement. <qualifier1>[_<qualifier2>...] est le format.

Vous pouvez combiner plusieurs qualificateurs dans un nom de fichier au même format.

\Assets\Images\logo.contrast-high_scale-400.png

Selon les outils et le flux de travail que vous utilisez pour la création de ressources, ou selon ce que vous trouvez le plus facile à lire et/ou à gérer, vous pouvez choisir une stratégie de nommage unique pour tous les qualificateurs, ou les combiner pour différents qualificateurs.

AlternateForm

Le alternateform qualificateur est utilisé pour fournir une autre forme d’une ressource à des fins spéciales. Cela est généralement utilisé uniquement par les développeurs d’applications japonaises pour fournir une chaîne furigana pour laquelle la valeur msft-phonetic est réservée (voir la section « Prise en charge de Furigana pour les chaînes japonaises pouvant être triées » dans Guide pratique pour préparer la localisation).

Votre système cible ou votre application doit fournir une valeur par rapport à laquelle alternateform les qualificateurs sont mis en correspondance. N’utilisez pas le msft- préfixe pour vos propres valeurs de qualificateur personnalisé alternateform .

Configuration

Il est peu probable que vous ayez besoin du nom du configuration qualificateur. Il peut être utilisé pour spécifier des ressources qui s’appliquent uniquement à un environnement de création donné, comme les ressources de test uniquement.

Le configuration qualificateur est utilisé pour charger une ressource qui correspond le mieux à la valeur de la variable d’environnement MS_CONFIGURATION_ATTRIBUTE_VALUE . Ainsi, vous pouvez définir la variable sur la valeur de chaîne qui a été affectée aux ressources appropriées, par exemple designer, ou test.

Comparez

Le contrast qualificateur est utilisé pour fournir des ressources qui correspondent le mieux aux paramètres de contraste élevé.

Custom

Votre application peut définir une valeur pour le custom qualificateur, puis les ressources sont chargées qui correspondent le mieux à cette valeur. Par exemple, vous pouvez charger des ressources en fonction de la licence de votre application. Au lancement de votre application, elle vérifie sa licence et l’utilise comme valeur pour le custom qualificateur en appelant SetGlobalQualifierValue, comme indiqué dans l’exemple de code.

public void SetLicenseLevel(BrandID brand)
{
    if (brand == BrandID.Premium)
    {
        ResourceContext.SetGlobalQualifierValue("Custom", "Premium", ResourceQualifierPersistence.LocalMachine);
    }
    else if (brand == BrandID.Standard)
    {
        ResourceContext.SetGlobalQualifierValue("Custom", " Standard", ResourceQualifierPersistence.LocalMachine);
    }
    else
    {
        ResourceContext.SetGlobalQualifierValue("Custom", "Trial", ResourceQualifierPersistence.LocalMachine);
    }
}

Dans ce scénario, vous devez ensuite donner à vos ressources des noms qui incluent les qualificateurs custom-premium, custom-standardet custom-trial.

DeviceFamily

Il est peu probable que vous ayez besoin du nom du devicefamily qualificateur. Vous pouvez et devriez éviter de l’utiliser chaque fois que possible, car il existe des techniques que vous pouvez utiliser à la place qui sont beaucoup plus pratiques et robustes. Ces techniques sont décrites dans Détection de la plateforme sur laquelle votre application s’exécute et Code adaptatif version.

Mais en dernier recours, il est possible d’utiliser des qualificateurs devicefamily pour nommer les dossiers qui contiennent vos vues XAML (une vue XAML est un fichier XAML qui contient la disposition et les contrôles de l’interface utilisateur).

\devicefamily-desktop\<MainPage.xaml, and other markup files to load when running on a desktop computer>
\devicefamily-mobile\<MainPage.xaml, and other markup files to load when running on a phone>

Vous pouvez également nommer des fichiers.

\MainPage.devicefamily-desktop.xaml
\MainPage.devicefamily-mobile.xaml

Dans les deux cas, chaque copie de MainPage.[<qualifier>].xaml partage un commun MainPage.xaml.cs, qui reste inchangé dans votre projet en termes de nom, d’emplacement et de contenu.

Vous pouvez également utiliser un qualificateur devicefamily pour nommer un fichier de ressources (.resw) ou un dossier. Par exemple, lorsque votre application s’exécute sur la famille d’appareils mobiles, l’élément <TextBlock x:Uid="DeviceFriendlyName"/> d’interface utilisateur utilise le texte et les ressources de premier plan définies dans votre Resources.devicefamily-mobile.resw fichier s’il contient

<data name="DeviceFriendlyName.Foreground">
    <value>Red</value>
</data>
<data name="DeviceFriendlyName.Text">
    <value>Mobile device</value>
</data>

Pour plus d’informations sur l’utilisation d’un fichier de ressources, consultez Localiser vos chaînes d’interface utilisateur.

DXFeatureLevel

Il est peu probable que vous ayez besoin du nom du dxfeaturelevel qualificateur. Il a été conçu pour être utilisé avec les ressources de jeu Direct3D, afin que les ressources de niveau inférieur soient chargées pour correspondre à une configuration matérielle de bas niveau particulière de l’époque. Mais la prévalence de cette configuration matérielle est maintenant si faible que nous vous recommandons de ne pas utiliser ce qualificateur.

HomeRegion

Le homeregion qualificateur correspond au paramètre de l’utilisateur pour le pays ou la région. Il représente l’emplacement d’accueil de l’utilisateur. Les valeurs incluent toute balise de région BCP-47 valide. Autrement dit, n’importe quel code de région iso 3166-1 alpha-2 à deux lettres, plus l’ensemble de codes géographiques numériques à trois chiffres ISO 3166-1 pour les régions composées (voir Composition des codes régionaux de la Division de statistique des Nations Unies M49). Les codes pour les « groupes économiques et autres sélectionnés » ne sont pas valides.

Langage

Un language qualificateur correspond au paramètre de langue d’affichage. Les valeurs incluent toute balise de langue BCP-47 valide. Pour obtenir la liste des langues, consultez le registre de sous-balises de langue IANA.

Si vous souhaitez que votre application prend en charge différents langages d’affichage et que vous avez des littéraux de chaîne dans votre code ou dans votre balisage XAML, déplacez ces chaînes hors du code/balisage et dans un fichier de ressources (.resw). Vous pouvez ensuite effectuer une copie traduite de ce fichier de ressources pour chaque langue prise en charge par votre application.

Vous utilisez généralement un language qualificateur pour nommer les dossiers qui contiennent vos fichiers de ressources (.resw).

\Strings\language-en\Resources.resw
\Strings\language-ja\Resources.resw

Vous pouvez omettre la language- partie d’un language qualificateur (c’est-à-dire le nom du qualificateur). Vous ne pouvez pas le faire avec les autres types de qualificateurs; et vous ne pouvez le faire que dans un nom de dossier.

\Strings\en\Resources.resw
\Strings\ja\Resources.resw

Au lieu de nommer des dossiers, vous pouvez utiliser language des qualificateurs pour nommer les fichiers de ressources eux-mêmes.

\Strings\Resources.language-en.resw
\Strings\Resources.language-ja.resw

Pour plus d’informations sur la localisation de votre application à l’aide de ressources de chaîne, consultez Localiser vos chaînes d’interface utilisateur et comment référencer une ressource de chaîne dans votre application.

LayoutDirection

Un layoutdirection qualificateur correspond à la direction de disposition du paramètre de langue d’affichage. Par exemple, une image peut avoir besoin d’être mise en miroir pour une langue de droite à gauche telle que l’arabe ou l’hébreu. Les panneaux de disposition et les images de votre interface utilisateur répondent correctement à la direction de la disposition si vous définissez leur propriété FlowDirection (voir Ajuster la disposition et les polices, et prendre en charge RTL). Toutefois, le layoutdirection qualificateur est destiné aux cas où un simple retournement n’est pas adéquat et vous permet de répondre à la directionnalité de l’ordre de lecture et de l’alignement du texte de manière plus générale.

Scale

Windows sélectionne automatiquement un facteur de mise à l’échelle pour chaque affichage en fonction de son PPP (points par pouce) et de la distance d’affichage de l’appareil. Consultez Pixels effectifs et facteur d’échelle. Vous devez créer vos images à plusieurs tailles recommandées (au moins 100, 200 et 400) afin que Windows puisse choisir la taille idéale ou utiliser la taille la plus proche et la mettre à l’échelle. Pour que Windows puisse identifier quel fichier physique contient la taille correcte de l’image pour le facteur d’échelle d’affichage, vous utilisez un scale qualificateur. L’échelle d’une ressource correspond à la valeur de DisplayInformation.ResolutionScale ou à la ressource la plus grande mise à l’échelle suivante.

Voici un exemple de définition du qualificateur au niveau du dossier.

\Assets\Images\scale-100\<logo.png, and other image files>
\Assets\Images\scale-200\<logo.png, and other image files>
\Assets\Images\scale-400\<logo.png, and other image files>

Cet exemple le définit au niveau du fichier.

\Assets\Images\logo.scale-100.png
\Assets\Images\logo.scale-200.png
\Assets\Images\logo.scale-400.png

Pour plus d’informations sur la qualification d’une ressource pour et scaletargetsize, consultez Qualifier une ressource d’image pour targetsize.

TargetSize

Le targetsize qualificateur est principalement utilisé pour spécifier les icônes d’association de types de fichiers ou les icônes de protocole à afficher dans Explorateur de fichiers. La valeur du qualificateur représente la longueur latérale d’une image carrée en pixels bruts (physiques). La ressource dont la valeur correspond au paramètre Affichage dans Explorateur de fichiers est chargée; ou la ressource avec la valeur la plus importante suivante en l’absence d’une correspondance exacte.

Vous pouvez définir des ressources qui représentent plusieurs tailles de valeur de targetsize qualificateur pour l’icône d’application (/Assets/Square44x44Logo.png) sous l’onglet Ressources visuelles du concepteur de manifeste de package d’application.

Pour plus d’informations sur la qualification d’une ressource pour et scaletargetsize, consultez Qualifier une ressource d’image pour targetsize.

Thème

Le theme qualificateur est utilisé pour fournir des ressources qui correspondent le mieux au paramètre de mode d’application par défaut ou au remplacement de votre application à l’aide de Application.RequestedTheme.

Thème clair de l’interpréteur de commandes et ressources non plaquées

La mise à jour Windows 10 mai 2019 a introduit un nouveau thème « light » pour l’interpréteur de commandes Windows. Par conséquent, certaines ressources d’application qui étaient précédemment affichées sur un arrière-plan sombre s’affichent désormais sur un arrière-plan clair. Pour les applications qui ont fourni des ressources altform-unplated pour les sélecteurs de barre des tâches et de fenêtre (Alt+Tab, Affichage des tâches, etc.), vous devez vérifier qu’elles présentent un contraste acceptable sur un arrière-plan clair.

Fourniture de ressources spécifiques à un thème clair

Les applications qui souhaitent fournir une ressource personnalisée pour le thème léger de l’interpréteur de commandes peuvent utiliser un nouveau qualificateur de ressource de formulaire de remplacement : altform-lightunplated. Ce qualificateur reflète le qualificateur altform-unplated existant.

Considérations relatives au niveau inférieur

Les applications ne doivent pas utiliser le theme-light qualificateur avec le altform-unplated qualificateur. Cela entraîne un comportement imprévisible sur RS5 et les versions antérieures de Windows en raison de la façon dont les ressources sont chargées pour la barre des tâches. Sur les versions antérieures de Windows, la version thème-light peut être utilisée incorrectement. Le altform-lightunplated qualificateur évite ce problème.

Comportement de compatibilité

Pour la compatibilité descendante, Windows inclut une logique pour détecter une icône monochromatique et case activée si elle contraste avec l’arrière-plan prévu. Si l’icône ne répond pas aux exigences de contraste, Windows recherche une version blanche contrastée de la ressource. Si ce n’est pas disponible, Windows revient à utiliser la version plaquée de la ressource.

API importantes