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 aux contextes d’exécution tels que le langage d’affichage, le contraste élevé, le facteur d’échelle d’affichage et bien d’autres. Pour ce faire, vous devez 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 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 de 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 à 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 de qualificateurs est contrast-standard, contrast-high, contrast-black, et contrast-white. Les noms des qualificateurs et les valeurs de qualificateur 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 des 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 des 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 du \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 du \Assets\Images\contrast-standard dossier sont chargés.

Utiliser des qualificateurs dans les noms de fichiers

Au lieu de créer et d’nommer des dossiers, vous pouvez utiliser un qualificateur pour nommer eux-mêmes les fichiers de ressources. Vous préférez 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 correspondante fonctionne de la même façon que pour les noms de fichiers que pour les noms de dossiers.

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

Reportez-vous à un identificateur de ressource de chaîne à partir du balisage XAML, reportez-vous à un identificateur de ressource de chaîne à partir du code et référencez une image ou une autre ressource à partir du balisage ET du code XAML.

Correspondances des 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 une pour le contraste standard, vous pouvez nommer ces ressources comme ceci.

\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, il s’agit d’une correspondance proche. Une correspondance réelle ne peut se produire que si le qualificateur contient une valeur réelle , comme celui-ci le fait. Dans ce cas, high est une valeur réelle pour contrast.

Le fichier nommé logo.png n’a aucun qualificateur de contraste sur celui-ci. 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 peut être trouvée, et donc la ressource logo.png est chargée.

Si vous deviez modifier le nom de celui-ci, le nom du logo.png logo.contrast-standard.pngfichier contient une valeur de qualificateur réelle. Avec un contraste élevé, il y aurait une correspondance réelle avec logo.contrast-standard.png, et c’est le fichier de ressources qui serait chargé. Par conséquent, 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 ensemble pour le contraste standard, vous pouvez utiliser des noms de dossiers plutôt que des noms de fichiers. Dans ce cas, omettre entièrement le 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 Le système de gestion des ressources.

Qualificateurs multiples

Vous pouvez combiner des qualificateurs dans les noms de dossiers et de fichiers. Par exemple, vous souhaiterez peut-être que votre application charge des ressources d’image lorsque le mode contraste élevé est activé et que le facteur d’échelle d’affichage est 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 que les autres fichiers soient chargés, 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 sur ce que vous trouvez le plus simple à 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 de ressource à des fins particulières. Il est généralement utilisé uniquement par les développeurs d’applications japonais pour fournir une chaîne furigana pour laquelle la valeur msft-phonetic est réservée (voir la section « Support Furigana pour les chaînes japonaises qui peuvent être triées » dans Comment préparer la localisation).

Votre système cible ou votre application doivent 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ées alternateform .

Configuration

Il est peu probable que vous aurez besoin du nom du configuration qualificateur. Il peut être utilisé pour spécifier des ressources applicables 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 . Vous pouvez donc définir la variable sur la valeur de chaîne qui a été affectée aux ressources pertinentes, par exemple designer, ou test.

Contraste

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

Personnalisée

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. Lorsque votre application démarre, elle vérifie sa licence et l’utilise comme valeur du 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 noms de ressources qui incluent les qualificateurs custom-premium, custom-standardet custom-trial.

DeviceFamily

Il est peu probable que vous aurez besoin du nom du devicefamily qualificateur. Vous pouvez et devez é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 la détection de la plateforme sur laquelle votre application s’exécute et du code adaptatif version.

Mais en dernier recours, il est possible d’utiliser des qualificateurs devicefamily pour nommer des dossiers contenant 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 partages est commune MainPage.xaml.cs, qui reste inchangée 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 (.reswou 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 aurez besoin du nom du dxfeaturelevel qualificateur. Il a été conçu pour être utilisé avec les ressources de jeu Direct3D, afin de charger des ressources de niveau inférieur afin qu’elles correspondent à une configuration matérielle de niveau inférieur particulière de l’heure. 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 n’importe quelle balise de région BCP-47 valide. Autrement dit, tout code de région à deux lettres ISO 3166-1 alpha-2 , ainsi que l’ensemble de codes géographiques à trois chiffres numériques ISO 3166-1 pour les régions composées (voir la composition de la Division des statistiques des Nations Unies M49 des codes régionaux). Les codes relatifs à « Sélection économique et autres regroupements » ne sont pas valides.

Langage

Un language qualificateur correspond au paramètre de langue d’affichage. Les valeurs incluent n’importe quelle 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érentes langues d’affichage et que vous disposez de 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 (autrement dit, 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 eux-mêmes les fichiers de ressources.

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

Consultez Localiser vos chaînes d’interface utilisateur pour plus d’informations sur la localisation de votre application à l’aide de ressources de chaîne et sur la façon de 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 ê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 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ù le découpage simple n’est pas adéquat et vous permet de répondre à la direction de l’ordre de lecture et de l’alignement de texte spécifiques de manière plus générale.

Mise à l’échelle

Windows sélectionne automatiquement un facteur d’échelle pour chaque affichage en fonction de son PPP (points par pouce) et de la distance d’affichage de l’appareil. Consultez les pixels effectifs et le 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 parfaite ou utiliser la taille la plus proche et la mettre à l’échelle. Pour que Windows puisse identifier le fichier physique qui 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 à 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 montre comment le définir 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 les deux scale et , consultez Qualifier une ressource d’image pour la taille des targetsizecibles.

TargetSize

Le targetsize qualificateur est principalement utilisé pour spécifier des icônes d’association de type de fichier ou des icônes de protocole à afficher dans Explorateur de fichiers. La valeur de qualificateur représente la longueur latérale d’une image carrée en pixels bruts (physiques). 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 du package d’application.

Pour plus d’informations sur la qualification d’une ressource pour les deux scale et , consultez Qualifier une ressource d’image pour la taille des targetsizecibles.

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 d’Application.RequestedTheme.

Thème clair de l’interpréteur de commandes et ressources nonplates

Le Mise à jour de mai 2019 de Windows 10 a introduit un nouveau thème « light » pour Windows Shell. Par conséquent, certaines ressources d’application qui étaient précédemment affichées sur un arrière-plan sombre seront désormais affichées sur un arrière-plan clair. Pour les applications qui ont fourni des ressources altform-nonplatées pour les commutateurs de barre des tâches et de fenêtre (Alt+Tab, Affichage des tâches, etc.), vous devez vérifier qu’ils ont un contraste acceptable sur un arrière-plan clair.

Fourniture de ressources spécifiques au thème clair

Les applications qui souhaitent fournir une ressource personnalisée pour le thème clair shell 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 de thème-lumière peut être utilisée de manière incorrecte. Le altform-lightunplated qualificateur évite ce problème.

Comportement de compatibilité

Pour la compatibilité descendante, Windows inclut la logique permettant de détecter des icônes monochromatiques et de vérifier s’il 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 de contraste de la ressource. Si ce n’est pas disponible, Windows revient à utiliser la version plate de la ressource.

API importantes