Адаптация ресурсов с учетом языка, масштаба, высокой контрастности и других квалификаторов

  • Статья

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

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

Дополнительные сведения о преимуществах локализации приложений см. в разделе Глобализация и локализация.

Имя квалификатора, значение квалификатора и квалификатор

Имя квалификатора — это ключ, сопоставленный с набором значений квалификатора. Ниже представлены имя и значения квалификатора для контрастности.

Контекст Имя квалификатора Значения квалификатора
Параметры высокой контрастности контрастность стандартная, высокая, черная, белая

Квалификатор образуется путем объединения имени и значения квалификатора. <qualifier name>-<qualifier value> — это формат квалификатора. contrast-standard является примером квалификатора.

Таким образом, для высокой контрастности используется набор квалификаторов contrast-standard, contrast-high, contrast-black и contrast-white. В именах и значениях квалификаторов регистр не учитывается. Например, contrast-standard и Contrast-Standard — это один и тот же квалификатор.

Использование квалификаторов в именах папок

Ниже приведен пример использования квалификаторов в именах папок, содержащих файлы ресурсов. Используйте квалификаторы в именах папок при наличии нескольких файлов ресурсов на квалификатор. В этом случае квалификатор устанавливается один раз на уровне папки и применяется ко всему ее содержимому.

\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>

Если назвать папки, как в примере выше, приложение использует параметр высокой контрастности для загрузки файлов ресурсов из папки, имя которой содержит соответствующий квалификатор. Таким образом, если параметру задано значение "Черная тема высокой контрастности", загружаются файлы ресурсов в папке \Assets\Images\contrast-black. Если параметру задано значение "Нет" (то есть режим высокой контрастности на компьютере не включен), загружаются файлы в папке \Assets\Images\contrast-standard.

Использование квалификаторов в именах файлов

Вместо создания и именования папок можно использовать квалификатор в именах самих файлов ресурсов. Это оптимальный вариант при наличии только одного файла ресурса на квалификатор. Вот пример.

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

Загружается файл, имя которого содержит наиболее соответствующий параметру квалификатор. Эта логика сопоставления работает одинаково как для имен файлов, так и для имен папок.

Ссылка на ресурс строки или изображения по имени

См. разделы Ссылка на идентификатор строкового ресурса из разметки XAML, Ссылка на идентификатор строкового ресурса из кода и Ссылки на изображения и другие ресурсы из кода и разметки XAML.

Фактические и нейтральные соответствия квалификаторов

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

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

Имя первого файла содержит квалификатор contrast-high. Этот квалификатор является фактическим соответствием для любого параметра высокой контрастности, если режим высокой контрастности включен. Иными словами, это близкое соответствие, поэтому ему отдается предпочтение. Фактическое совпадение возможно, только если квалификатор содержит фактическое значение, как в этом случае. В данном случае high — фактическое значение для contrast.

Файл с именем logo.png не содержит квалификатора контрастности. Отсутствие квалификатора является нейтральным значением. Если не удается найти предпочтительное значение, нейтральное значение используется в качестве резервного соответствия. В этом примере, если режим высокой контрастности отключен, фактического соответствия нет. Наиболее близкое соответствие, которое удается найти, — нейтральное, поэтому загружается ресурс logo.png.

Если изменить имя файла logo.png на logo.contrast-standard.png, оно будет содержать фактическое значение квалификатора. При выключенном режиме высокой контрастности файл ресурса logo.contrast-standard.png был бы фактическим соответствием, и именно он и был бы загружен. Таким образом, были бы загружены одни и те же файлы при одинаковых условиях, но из-за разных соответствий.

Если вам нужен только один набор ресурсов для высокой контрастности и один — для стандартной контрастности, можно использовать имена папок вместо имен файлов. В этом случае полный пропуск имени папки обеспечивает нейтральное соответствие.

\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>

Дополнительные сведения о принципах соответствий квалификаторов см. в разделе Система управления ресурсами.

Несколько квалификаторов

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

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

Для загрузки logo.png и других файлов параметры должны соответствовать обоим квалификаторам.

Кроме того, можно объединить несколько квалификаторов в одном имени папки.

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

При добавлении нескольких квалификаторов в имя папки они разделяются символом подчеркивания. <qualifier1>[_<qualifier2>...] — это формат .

Можно объединить несколько квалификаторов в имени файла в одном формате.

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

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

AlternateForm

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

Целевая система или приложение должны предоставить значение, с которым сопоставляются квалификаторы alternateform. При указании своих значений квалификатора alternateform не добавляйте префикс msft-.

Конфигурация

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

Квалификатор configuration используется для загрузки ресурса, наиболее соответствующего значению переменной среды MS_CONFIGURATION_ATTRIBUTE_VALUE. Таким образом, можно задать для переменной строковое значение, присвоенное релевантным ресурсам, например designer или test.

Контраст

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

Особые настройки

Приложение может установить значение для квалификатора custom, после чего загружаются ресурсы, наиболее соответствующие этому значению. Например, можно загружать ресурсы с учетом лицензии приложения. При запуске приложение проверяет лицензию и использует ее как значение для квалификатора custom путем вызова метода SetGlobalQualifierValue, как показано в примере кода.

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);
    }
}

Далее в этом сценарии предоставляются имена ресурсов, содержащие квалификаторы custom-premium, custom-standard и custom-trial.

DeviceFamily

Маловероятно, что вам потребуется имя квалификатора devicefamily. Вы можете (и вам следует) избегать его использования, так как вместо этого можно использовать более удобные и надежные способы. Эти способы описаны в разделах Определение платформы, на которой работает приложение и Адаптивный к версии код.

Но в крайнем случае можно использовать квалификаторы devicefamily для именования папок, содержащих ваши представления XAML (представление XAML — это файл XAML, содержащий макет пользовательского интерфейса и элементы управления).

\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>

Кроме того, можно именовать файлы.

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

В обоих случаях каждая копия MainPage.[<qualifier>].xaml содержит общий файл MainPage.xaml.cs, который остается неизменным в проекте с точки зрения имени, расположения и содержимого.

Также можно использовать квалификатор devicefamily для именования файла (.resw) или папки ресурсов. Например, если приложение запускается на мобильном семействе устройств, для элемента <TextBlock x:Uid="DeviceFriendlyName"/> пользовательского интерфейса будут использоваться ресурсы текста и переднего плана, определенные в содержащемся в нем файле Resources.devicefamily-mobile.resw

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

Дополнительные сведения об использовании файла ресурсов см. в разделе Локализация строк пользовательского интерфейса.

DXFeatureLevel

Маловероятно, что вам потребуется имя квалификатора dxfeaturelevel. Этот квалификатор предназначен для использования с игровыми ресурсами Direct3D. Он обеспечивает загрузку низкоуровневых ресурсов в соответствии с распространенной на тот момент конфигурацией оборудования крайне низкого уровня. Но на сегодняшний день такая конфигурация встречается настолько редко, что мы не рекомендуем использовать этот квалификатор.

HomeRegion

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

Язык

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

Если вы хотите, чтобы ваше приложение поддерживало разные языки интерфейса, а в вашем коде или разметке XAML есть строковые литералы, переместите эти строки из кода или разметки в файл ресурсов (.resw). Затем можно создать переведенную копию этого файла ресурсов для каждого языка, поддерживаемого вашим приложением.

Как правило, квалификатор language используется для именования папок, содержащих файлы ресурсов (.resw).

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

Можно опустить часть language- квалификатора language (то есть имя квалификатора). Это можно сделать только с этим типом квалификатора и только в имени папки.

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

Вместо именования папок можно использовать квалификаторы language для именования самих файлов ресурсов.

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

Дополнительные сведения об использовании строковых ресурсов для обеспечения возможности локализации приложения и о добавлении в приложение ссылок на строковые ресурсы см. в разделе Локализация строк пользовательского интерфейса.

LayoutDirection

Квалификатор layoutdirection соответствует направлению макета параметра языка интерфейса. Например, для арабского языка или иврита необходимо отразить изображение слева направо. Панели макета и изображения в пользовательском интерфейсе будут реагировать на направление макета должным образом, если настроить их свойствоFlowDirection (см. раздел Настройка макета и шрифтов, реализация поддержки написания справа налево). Однако если простого отражения недостаточно, используется квалификатор layoutdirection. Он дает возможность реагировать на определенный порядок чтения и выравнивание текста более общими способами.

Масштабирование

Windows автоматически выбирает коэффициент масштабирования для каждого дисплея на основе его показателя DPI (точек на дюйм) и расстояния от экрана устройства. См. раздел Эффективные пиксели и коэффициент масштабирования. Следует создавать изображения в нескольких рекомендуемых размерах (по крайней мере 100, 200 и 400), чтобы Windows могла либо выбрать идеальный размер, либо использовать ближайший размер с масштабированием. Для того чтобы Windows могла определить, какой физический файлы содержит изображение нужного размера для коэффициента масштабирования дисплея, используйте квалификатор scale. Масштаб ресурса сопоставляется со значением DisplayInformation.ResolutionScale или со следующим ресурсом с наибольшим масштабом.

Вот пример настройки квалификатора на уровне папки.

\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>

А в этом примере квалификатор настраивается на уровне файла.

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

Сведения о квалификации ресурса для scale и targetsize одновременно см. в разделе Квалификация ресурса изображения по targetsize.

TargetSize

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

Можно определить ресурсы, представляющие несколько размеров значения квалификатора targetsize для значка приложения (/Assets/Square44x44Logo.png), на вкладке "Визуальные ресурсы" конструктора манифеста пакета приложения.

Сведения о квалификации ресурса для scale и targetsize одновременно см. в разделе Квалификация ресурса изображения по targetsize.

Тема

Квалификатор theme используется для предоставления ресурсов, наиболее соответствующих установленному по умолчанию параметру режима приложения или переопределению приложения с использованием Application.RequestedTheme.

Светлая тема оболочки и неплатежированные ресурсы

В обновлении Windows 10 за май 2019 г. появилась новая "светлая" тема для оболочки Windows. В результате некоторые ресурсы приложения, которые ранее отображались на темном фоне, теперь будут отображаться на светлом фоне. Для приложений, которые предоставляют ресурсы без покрытия altform для переключателей панели задач и окон (ALT+TAB, представление задач и т. д.), следует убедиться, что они имеют приемлемую контрастность на светлом фоне.

Предоставление ресурсов, относящихся к светлой теме

Приложения, которые хотят предоставить специализированный ресурс для светлой темы оболочки, могут использовать новый альтернативный квалификатор ресурса формы: altform-lightunplated. Этот квалификатор отражает существующий квалификатор altform-unplated.

Рекомендации по нижнему уровням

Приложения не должны использовать theme-light квалификатор с квалификатором altform-unplated . Это приведет к непредсказуемому поведению в RS5 и более ранних версиях Windows из-за способа загрузки ресурсов для панели задач. В более ранних версиях Windows версия theme-light может использоваться неправильно. Квалификатор altform-lightunplated позволяет избежать этой проблемы.

Поведение совместимости

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

Важные API