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

  • Статья

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

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

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

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

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

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

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

Таким образом, для высокой контрастности набор квалификаторов — contrast-standard, contrast-highcontrast-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>

Если вы назовете папки, как показано в приведенном выше примере, приложение использует параметр высокой контрастности для загрузки файлов ресурсов из папки с именем соответствующего квалификатора. Таким образом, если параметр имеет значение High Contrast Black, файлы ресурсов в папке \Assets\Images\contrast-black загружаются. Если параметр имеет значение None (то есть компьютер не находится в режиме высокой контрастности), файлы ресурсов в \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 используется для предоставления альтернативной формы ресурса для определенной специальной цели. Обычно это используется только японскими разработчиками приложений для предоставления строки furigana, для которой зарезервировано значение msft-phonetic (см. раздел "Поддержка Furigana для японских строк, которые можно отсортировать" в разделе "Подготовка к локализации").

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

Настройка

Вряд ли потребуется 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 альфа-2 с двумя буквами, а также набор кодов регионов ISO 3166-1 числовых трехзначных географических кодов для составных регионов (см . состав кодов регионов в отделе статистики Организации Объединенных Наций 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 (см. раздел "Настройка макета и шрифтов" и поддержка RTL). Однако квалификатор предназначен для случаев, 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 приложения (/Assets/Square44x44Logo.png) на вкладке "Визуальные ресурсы" конструктора манифеста пакета приложения.

Сведения о квалификации ресурса для обоих scale и 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