Именование ресурсов с помощью квалификаторов (HTML)

Статья
01/29/2016

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

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

Квалификаторы ресурсов

Файловые и строковые ресурсы можно адаптировать к разным масштабам отображения, языкам пользовательского интерфейса, режимам высокой контрастности и другим контекстам. Квалификаторы ресурсов — это модификаторы папки и имени файла, которые определяют контекст использования версии ресурса.

Стандартное соглашение о наименовании предполагает следующий формат:

foldername/qualifiername-value_qualifiername-value/filename.qualifiername-value_qualifiername-value.ext

Пример.

Images/en-US/homeregion-USA/logo.scale-100_contrast-white.png

загружается вызовом

Images/logo.png

Примечание Рекомендуется пометить язык по умолчанию и строковые файлы ресурсов (например, en-US\resources.resw), а также стандартный размер изображений (например, logo.scale-100.png), даже если эти файлы не будут локализованы или адаптированы для разных разрешений.

Полные имена папок анализируются по квалификаторам. Затем имена папок сопоставляются с набором квалификаторов либо обрабатываются как часть логического пути к файлу. Часть имени файла до расширения считается маркером, обозначающим квалификаторы. Квалификаторы разделяются символами подчеркивания и обычно задаются именем и значением (кроме языка в имени папки).

В зависимости от рабочего процесса и нужд приложения разработчики приложений могут использовать имена папок и (или) файлов для указания активов для заданного набора контекстов.

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

en-us\logo.scale-100.png
en-us\logo.scale-140.png
fr-fr\logo.scale-100.png
fr-fr\logo.scale-140.png

Тогда пользователь, предпочитающий языковой стандарт «английский (США)» на экране с масштабом 140, увидит изображение en-us\logo.scale-140.png. Дополнительные сведения о выборе ресурсов в более сложных сценариях резервных действий см. в статье Контекст ресурса.

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

Важно Здесь описаны форматы для сегмента квалификатора в имени файла (или имени папки в случае языков). Один или несколько квалификаторов должны отображаться как сегмент в полном имени файла, которое следует после имени ресурса и перед расширением файла, как в этом формате, состоящем в основном из заполнителей: name**.qualifiers.**ext. Точки (.) здесь важны, поскольку они служат синтаксическими разделителями между сегментами. Использовать символ точки в иных целях внутри форматов квалификаторов нельзя.

Язык (приложение)

Квалификатор языка указывает язык ресурса BCP-47. Для имен файлов требуется квалификатор lang или language и тег языка, а для папок достаточно только тега языка. Список языков см. в реестре подтегов языков IANA.

Форматы имени папки:

<Any BCP-47 language tag>
lang-<Any BCP-47 language tag>
language-<Любой тег языка BCP-47>

Форматы имени файла:

lang-<Any BCP-47 language tag>
language-<Any BCP-47 language tag>

Примеры.

es-MX/resources.resw
language-de-DE/UI.resw
images/logo.lang-fr-FR.png

Квалификатор языка сравнивается со списком языков приложения. При динамическом изменении языка приложения создаются события (см. ResourceContext.QualifierValues). Приложению не нужно задавать или переопределять язык.

Масштаб

Квалификатор scale указывает коэффициент масштабирования ресурса. Это обычно используется для просмотра изображений на устройстве с высоким разрешением или при увеличении элементов интерфейса. Масштаб ресурса сопоставляется со значением Windows.Graphics.Display.DisplayProperties.ResolutionScale или со следующим ресурсом с наибольшим масштабом. Если для ресурса используется квалификатор scale, не следует использовать квалификатор targetsize.

Квалификаторы масштаба:

scale-80 (действителен только для ресурсов, определенных в манифесте приложения)
scale-100
scale-140
scale-180 (Windows)
scale-240 (Windows Phone)

Информация об изменении масштаба во время выполнения распространяется в форме событий (см. ResourceContext.QualifierValues).

Контрастность

Квалификатор контрастности указывает контрастность темы для системы. Значение Standard используется, когда все темы с высокой контрастностью отключены. Значение High действительно в любом режиме высокой контрастности. Значение Black указывает на предпочтение изображений с белым передним планом и черным фоном. Значение White указывает на предпочтение изображений с черным передним планом и белым фоном. Параметры темы High Contrast #1 и High Contrast #2 соответствует значению квалификатора Black.

contrast-standard
contrast-high
contrast-black
contrast-white

Homeregion

Квалификатор homeregion представляет домашнее расположение пользователя. Он обычно задается при установке Windows и доступен на панели управления. Этот квалификатор (ResourceContext.QualifierValues) обычно переопределяется, если становится известен какой-то другой поставщик данных местоположения. Его значением может быть любой действительный тег региона BCP-47, то есть любой двухбуквенный код региона iso-3166-1 alpha 2 или трехзначный географический код для составных регионов iso-3166-1 numeric (см. состав кодов регионов подразделения статистики ООН M49). При этом коды "выбранных экономических и других групп" недействительны.

Формат местоположения:

homeregion-<Region Code>

Примеры.

homeregion-us
homeregion-jp
homeregion-419

Квалификатор местоположения соответствует любому составному региону верхнего уровня.

Целевой размер

Квалификатор targetsize может задавать ресурсы конкретного размера (в пикселях). Он используется в основном для указания значков сопоставления типов файлов и значков протоколов в проводнике для рабочего стола. Квалификатор обычно используется для квадратных изображений или значков и обозначает только одно измерение изображения. Система или приложение, которые запрашивают ресурс (ResourceContext.QualifierValues), должны явно указать квалификатор targetsize. Значения по умолчанию нет. Если для ресурса используется квалификатор targetsize, не следует использовать квалификатор scale.

Формат целевого размера:

targetsize-<any positive integer>

Примеры.

targetsize-16
targetsize-96

Контекст targetsize соответствует следующему по величине ресурсу, отвечающему остальным требованиям.

Направление макета

Квалификатор макета используется для указания ресурсов, которые соответствуют определенному порядку чтения и выравниванию текста. Например, для арабского языка или иврита необходимо отразить изображение слева направо. Большинство приложений делают это автоматически во время работы, поэтому данный квалификатор нужен только в нестандартных случаях. Дополнительные сведения см. в разделе Адаптация макета под языки с написанием справа налево и локализация шрифтов.

Формат направления макета:

layoutdir-LTR
layoutdir-RTL
layoutdir-TTBLTR
layoutdir-TTBRTL

Configuration

Квалификатор конфигурации используется для указания ресурсов, применимых только в данной среде времени разработки, например тестовых ресурсов. Большинству разработчиков этот квалификатор не понадобится. Переменной среды MS_CONFIGURATION_ATTRIBUTE_VALUE можно задать строковое значение, которое присвоено релевантным ресурсам (таким как test).

Формат конфигурации:

config-<MS_CONFIGURATION_ATTRIBUTE_VALUE>

Примеры.

config-test
config-designer

Alternateform

С помощью квалификатора альтернативной формы можно задать альтернативную форму ресурса для особых целей. Он нужен главным образом японским разработчикам для создания строк фуригана, для которых зарезервировано значение msft-phonetic. Система или приложение должны указать значение для использования этого квалификатора в конкретных ситуациях. Значения по умолчанию нет. При указании своих значений не добавляйте префикс msft-.

Формат альтернативной формы:

altform-<Any string between 1 and 16 chars>

Примеры.

altform-msft-phonetic
altform-myapp-special

Уровень компонентов DirectX

Квалификатор уровня компонентов DirectX представляет уровень компонентов DirectX для графических адаптеров, которые будут выполнять отрисовку ресурса. Обычно это используется для отображаемых ресурсов Direct3D в играх. Уровень компонентов DirectX для ресурса будет отвечать значению, явно заданному приложением в контексте ресурсов. Если ресурс с точно заданным значением уровня компонентов DirectX недоступен, то используется ресурс с ближайшим меньшим значением.

Примечание Квалификатор уровня компонентов DirectX поддерживается начиная с версии Windows 8.1.

Квалификатор уровня компонентов DirectX может иметь два формата. Поддерживаемые значения — DX9, DX10 и DX11.

Формат функционального уровня DirectX

DXFeatureLevel-<value>
DXFL-<value>

Примеры.

DXFeatureLevel-DX10
DXFL-DX11

Примечания

Как уже говорилось, любые из этих форматов можно комбинировать в наборе квалификаторов, если нужно поддерживать несколько шаблонов квалификаторов для одного и того же сценария ресурса. Символ подчеркивания (_) используется в качестве разделителя между шаблонами квалификаторов. Например, вот путь к файлу ресурсов, который поддерживает конфигурацию, масштабирование и направление макета в явном виде: logo.config-test_scale-100_layoutdir-LTR.png