Comment charger des ressources de type chaîne (HTML)

Article
01/28/2016

[ Cet article est destiné aux développeurs Windows 8.x et Windows Phone 8.x qui créent des applications Windows Runtime. Si vous développez une application pour Windows 10, voir la Documentation ]

Vous pouvez charger des ressources de type chaîne à partir de divers objets, notamment des fichiers de ressources, des bibliothèques, des contrôles, ainsi que des packages et des manifestes d’application.

Chargement de chaînes à partir de fichiers de ressources

Les ressources de type chaîne sont créées dans des fichiers de ressources et des identificateurs de ressource permettent d’y faire référence. Pour obtenir une présentation des grandes lignes du chargement de ressources de type chaîne, voir Démarrage rapide : utilisation de ressources de type chaîne.

La plupart des applications ont besoin d’un seul fichier de ressources par défaut (<language>/Resources.resjson) et peuvent faire référence à leurs ressources en utilisant un chemin d’accès relatif à des clés de ce fichier (exemple : /String1). Cependant, dans certaines applications, il convient de scinder les ressources en plusieurs fichiers de ressources afin de garantir la séparation des composants.

Par exemple :

Nom de fichier :

Strings/en-US/Errors.resjson

Une référence à partir du balisage :

<span data-win-res="{textContent: '/Errors/AlreadyRegistered'}"></span>

Une référence à partir du code :

WinJS.Resources.getString('/Errors/AlreadyRegistered');

L’identificateur de ressource adopte la forme **/ResourceFileName/**StringName. Notez que le nom du fichier de ressources n’inclut ni l’extension, ni le chemin d’accès au dossier. Les noms de fichier de ressources doivent donc être uniques au sein d’un composant ou d’un projet.

Chargement de chaînes à partir de bibliothèques et de contrôles

Les applications disposent souvent de plusieurs composants ou deviennent dépendantes de bibliothèques, par exemple des bibliothèques de classes portables .NET, d’autres bibliothèques de classes compatibles et des bibliothèques de contrôles.

Si possible, les contrôles et les bibliothèques doivent tenter de réduire le nombre de ressources et laisser à l’application le soin de les fournir. Si une bibliothèque doit absolument fournir des ressources, elle doit également permettre aux applications de remplacer ces ressources sous forme de données d’entrée. Cela peut s’avérer nécessaire si la bibliothèque n’a pas la même portée de localisation que l’application qui l’utilise.

Par exemple :

var rating = new WinJS.UI.RatingsControl(el, {label: 'Please Rate', image: 'images/star.png'});

Le contrôle doit afficher les chaînes personnalisées telles qu’elles lui sont passées. En outre, dans la mesure du possible, il doit laisser l’application gérer la localisation.

var control = new Control(el, {commands: [
    {label: R.getString('Reply')}, 
    {label: R.getString('ReplyAll')
    ]});

En règle générale, les composants ou les fichiers bibliothèques sont ajoutés dans un sous-dossier du package où ils sont inclus au cours du processus de création, de la même manière que leurs ressources de type chaîne. Leur identificateur de ressource prend généralement la forme suivante :

ClassLibraryOrAssemblyName**/ResourceFileName/**StringName

Par programme, les bibliothèques peuvent se procurer leur propre élément ResourceLoader pour leurs ressources. Par exemple, le code qui suit illustre comment une bibliothèque peut se procurer un élément ResourceLoader pour son propre fichier de ressources :


var resources = Windows.ApplicationModel.Resources;
var RL = new resources.ResourceLoader('ContosoControl/Resources');
RL.getString('loadingStr'); // which came from ContosoControl's Resources

Chargement de chaînes à partir d’autres packages

Les ressources de chaque package d’application sont gérées séparément et sont accessibles par le biais d’un objet ResourceMap distinct, de niveau supérieur, lui-même accessible à partir de l’élément ResourceManager actuel. Au sein de chaque package, divers composants peuvent avoir leurs propres valeurs ResourceMap pour Subtree.

Les packages d’infrastructure peuvent avoir accès à leurs propres ressources avec un URI plus absolu :

Pour en savoir plus sur les URI ms-resource, voir Schémas d’URI.

Chargement de chaînes à partir de contrôles JavaScript

Les contrôles JavaScript qui fournissent des chaînes par défaut doivent utiliser WinJS.Resources.getString pour extraire leurs propres chaînes.

Les documents HTML chargés dans le contexte web (avec ms-app-web:) n’ont pas accès aux API Windows Runtime. C’est pourquoi, dans le code JavaScript, vous devez inclure des contrôles JavaScript qui ont été rédigés pour utiliser l’élément WinJS.Resources.getString. Dans le contexte web, l’élément WinJS.Resources.getString recherche finalement un ID donné, en tant que propriété d’un objet String global.

var strings = { 'String1' : 'Hello' };
WinJS.Resources.getString('String1');

Vous pouvez également remplacer la fonction WinJS.Resources.getString pour rechercher des ressources à partir d’un emplacement différent.

WinJS.Resources.getString = function(id){
    return getStringFromOtherService(id);
}

Chargement de chaînes à partir du manifeste d’applications

Tous les logs et chaînes affichables dans le manifeste sont localisables. Les logos peuvent également être adaptés pour les modes Échelle et Contraste élevé. Il est possible d’ajouter des références de chaîne à la place d’une chaîne codée en dur, en insérant un URI ms-resource: spécifié par un schéma dans les données du manifeste (cette opération est généralement effectuée dans l’interface utilisateur à onglets de Visual Studio dédiée à la modification de l’élément appxmanifest). Par exemple, l’élément ms-resource:String1 fait référence à une chaîne appelée String1 dans le fichier de ressources Resources.resw, tandis que l’élément ms-resource:/ManifestStrings/Shortname fait référence à une chaîne appelée Shortname dans le fichier de ressources ManifestStrings.resw.

Chargement de chaînes pour une langue ou un contexte spécifiques

L’objet ResourceContext par défaut (obtenu de ResourceManager) représente l’état actuel auquel les ressources correspondent. L’objet ResourceContext contient tous les divers qualificateurs de l’utilisateur et de l’ordinateur actuels. Bien que chaque qualificateur puisse être remplacé, cela n’est pas conseillé. La plupart des qualificateurs possèdent un fournisseur de données système qu’il est préférable, dans certains cas, de modifier par le biais d’une API distincte (c’est-à-dire PrimaryLanguageOverride) ou de laisser tel quel.

Pour en savoir plus sur les qualificateurs, voir Comment nommer des ressources à l’aide de qualificateurs.

L’élément ResourceManager conserve l’objet contextuel par défaut d’après lequel les recherches de ressources ont lieu. Dans certains cas particuliers, il peut être utile de se montrer explicite sur la langue, l’échelle ou tout autre qualificateur de contexte lorsque l’application charge les ressources. Par exemple, une application peut autoriser un utilisateur à choisir une autre langue pour les info-bulles ou les messages d’erreur. Les recherches peuvent spécifier leur propre objet contextuel remplacé explicite pour influencer la ressource choisie. Pour spécifier un contexte explicite, dans lequel la propriété Languages est remplacée délibérément, procédez comme suit :

var rcns = Windows.ApplicationModel.Resources.Core;

var context = new rcns.ResourceContext(); // deliberately not using getForCurrentView()
context.languages = new Array('fr-fr');
var resourceMap = rcns.ResourceManager.current.mainResourceMap.getSubtree('Resources');
var str = resourceMap.getValue('string1', context).ValueAsString;

Une autre technique consiste à appeler l’élément ResourceContext.SetGlobalQualifierContext avant l’élément ResourceContext.GetForCurrentView. Pour les besoins du scénario de langue, définissez le qualificateur language sur une nouvelle valeur. Si vous procédez ainsi, la différence avec la première méthode repose sur le fait que la modification apportée au qualificateur et au contexte porte sur l’ensemble des recherches touchant les ressources, et non à l’élément ResourceContext spécifique que vous avez créé à des fins d’utilisation pour l’appel GetValue unique. Voir aussi ApplicationLanguages.PrimaryLanguageOverride.

Événements et changements de contexte

Il se peut qu’une application soit en cours d’exécution lorsque le système est modifié. Cela entraîne l’utilisation d’un ensemble de qualificateurs différent. L’activation du mode Contraste élevé par l’utilisateur est un exemple de ce type de changement. Divers changements système appellent des événements dans l’objet ResourceContext.

Dans JavaScript, le moyen le plus simple pour écouter ces événements repose sur la méthode addEventListener :

WinJS.Resources.addEventListener('contextchanged', refresh, false);

Après avoir détecté l’événement, les applications peuvent retraiter le document afin que les ressources correctes puissent être chargées.

function refresh(){
    WinJS.Resources.processAll(); // Refetch string resources.
}

Le fait de retraiter les ressources peut entraîner la réinitialisation des valeurs liées aux données au sein des ressources, dans la mesure où la nouvelle ressource est appliquée directement à la propriété de l’élément. Si la ressource contient des emplacements de liaison de données, veillez à rétablir la liaison lors du retraitement.