Загрузка строковых ресурсов (HTML)

Статья
01/29/2016

[ Эта статья адресована разработчикам приложений среды выполнения Windows для Windows 8.x и Windows Phone 8.x. В случае разработки приложений для Windows 10 см. раздел последняя документация]

Строковые ресурсы можно загружать из таких объектов, как файлы ресурсов, библиотеки и элементы управления, а также из пакетов и манифестов приложений.

Загрузка строк из файлов ресурсов

Строковые ресурсы создаются в файлах ресурсов, а обращение к ним производится по идентификаторам ресурсов. Вводная информация о загрузке строковых ресурсов приведена в разделе Краткое руководство. Использование строковых ресурсов.

Для большинства приложений достаточно одного заданного по умолчанию файла ресурсов на язык (<language>/Resources.resjson), и они могут ссылаться на свои ресурсы с помощью относительного пути к ключам в этом файле (например, /String1). Но в некоторых приложениях имеет смысл распределить ресурсы по нескольким файлам ресурсов, чтобы обеспечить разделение компонентов.

Пример.

Имя файла:

Strings/en-US/Errors.resjson

Ссылка из разметки:

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

Ссылка из кода:

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

Идентификатор ресурса имеет вид **/ResourceFileName/**StringName. Обратите внимание, что имя файла ресурса не включает в себя расширение или путь к папке. Таким образом, файлы ресурсов должны иметь уникальные имена в пределах компонента или проекта.

Загрузка строк из библиотек и элементов управления

Часто приложения имеют несколько компонентов или содержат зависимости от библиотек, таких как переносимые библиотеки классов .NET, другие совместимые библиотеки классов и библиотеки элементов управления.

По возможности следует сокращать количество ресурсов в элементах управления и библиотеках и делать так, чтобы их предоставляло приложение. Если библиотека все же вынуждена предоставлять ресурсы, то приложения должны иметь возможность заменять их при вызове. Это может понадобиться, если библиотека и приложение используют разные области локализации.

Пример.

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

Элемент управления должен отображать пользовательские строки, переданные ему, в точности без изменений и там, где это возможно, позволять приложению обрабатывать локализацию.

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

Компоненты и файлы библиотек обычно добавляются во вложенную папку своего пакета при сборке, подобно строковым ресурсам. Их идентификаторы ресурсов обычно имеют следующий формат:

ClassLibraryOrAssemblyName**/ResourceFileName/**StringName

Библиотеки также могут программно запрашивать ResourceLoader для собственных ресурсов. Например, приведенный ниже код показывает, как библиотека может получить ResourceLoader для своих файлов ресурсов:


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

Загрузка строк из других пакетов

Управление ресурсами каждого пакета приложения и доступ к ним осуществляются раздельно через индивидуальные объекты верхнего уровня ResourceMap, доступные из текущего диспетчера ResourceManager. Различные компоненты в одном пакете могут иметь свои собственные значения ResourceMap Subtree.

Платформенные пакеты могут обращаться к собственным ресурсам с использованием более абсолютного идентификатора ресурса (URI):

Подробнее об URI ms-resource см. в Схемах URI.

Загрузка строк из элементов управления JavaScript

Элементы управления JavaScript, которые предоставляют строки по умолчанию, должны использовать метод WinJS.Resources.getString для чтения собственных строк.

HTML-документы, загруженные в веб-контекст (с использованием URI ms-app-web:), не имеют доступа к API среды выполнения Windows. Поэтому в коде на JavaScript следует применять элементы управления JavaScript, использующие метод WinJS.Resources.getString. В веб-контексте WinJS.Resources.getString делает обратный запрос, чтобы найти заданный идентификатор в свойствах глобального строкового объекта.

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

Можно также переопределить метод WinJS.Resources.getString, чтобы он получал ресурсы из другого места.

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

Загрузка строк из манифеста приложения

Все отображаемые строки и логотипы в манифесте можно локализовать. Логотипы также можно адаптировать к масштабу и режиму высокой контрастности. Ссылки на строки можно добавить вместо жестко заданных строк, добавив указанный в схеме ms-resource: URI в данные манифеста (обычно это делается в пользовательском интерфейсе Visual Studio с вкладками для редактирования appxmanifest). Например, ms-resource:String1 указывает на строку String1 в файле ресурсов Resources.resw, а ms-resource:/ManifestStrings/Shortname указывает на строку Shortname в файле ресурсов ManifestStrings.resw.

Загрузка строк для конкретного языка или контекста

Стандартный объект ResourceContext, полученный из ResourceManager, характеризует текущее состояние, соответствующее ресурсам. Объект ResourceContext содержит все возможные значения квалификатора для текущего пользователя и компьютера. Хотя каждый квалификатор можно переопределить, делать это не рекомендуется. У большинства квалификаторов есть системный поставщик данных, который в некоторых случаях лучше всего изменять с помощью отдельного API (то есть PrimaryLanguageOverride) или не изменять вовсе.

Подробнее о различных квалификаторах: Именование ресурсов с помощью квалификаторов.

В объекте ResourceManager хранится объект контекста по умолчанию, относительно которого производится поиск ресурсов. Иногда полезно явно указывать квалификатор языка, масштаба или другого контекста при скачивании ресурсов программой. Например, приложение может предоставить пользователю возможность выбрать другой язык для подсказок или сообщений об ошибках. Чтобы повлиять на выбор ресурса, компоненты, выполняющие поиск, могут явно указывать собственные переопределенные объекты контекста. Как явно указать контекст, если свойство Languages намеренно переопределено:

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;

Другой метод, который можно использовать для вызова ResourceContext.SetGlobalQualifierContext до вызова ResourceContext.GetForCurrentView. Для сценария языка квалификатору language присваивается новое значение. Если вы это делаете, разница заключается в том, что изменение квалификатора и контекста теперь применимы ко всем поискам ресурсов, а не только к ResourceContext, созданному для использования с единственным вызовом GetValue. См. также ApplicationLanguages.PrimaryLanguageOverride.

События и изменения контекста

Приложение может еще выполняться, когда система меняется. Это приведет к использованию другого набора квалификаторов. Одним из таких изменений может быть переход пользователя в режим высокой контрастности. Различные изменения в системе вызывают события объекта ResourceContext.

Простейший способ организовать прослушивание этих событий в JavaScript — с помощью метода addEventListener:

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

Обнаружив событие, приложения смогут повторно обработать документ, чтобы можно было загрузить правильные ресурсы.

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

Повторная обработка ресурсов может привести к сбросу в ресурсе значений, связанных с данными, в то время как новый ресурс применяется непосредственно к свойству элемента. Если ресурс содержит гнезда привязки к данным, обязательно выполняйте повторную привязку при повторной обработке.