Поделиться через

Настраивайте ресурсы под язык, масштабирование, высокую контрастность и другие квалификаторы

В этом разделе объясняется общее понятие квалификаторов ресурсов, их использование и назначение каждого из квалификаторов. См. 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>

Если вы назовете папки как в примере выше, приложение будет использовать параметр высокой контрастности для загрузки файлов ресурсов из папки, имя которой соответствует соответствующему квалификатору. Таким образом, если параметр имеет значение 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 для имен папок, содержащих представления 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 соответствует параметру пользователя для страны или региона. Он представляет домашнее расположение пользователя. Значения включают любой допустимый тег региона 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 соответствует направлению макета, определяемому параметром языка отображения. Например, может потребоваться зеркальное отображение изображения для языка справа налево, например арабского или иврита. Панели макета и изображения в вашем пользовательском интерфейсе будут корректно реагировать на направление макета, если задать свойство 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 для значка приложения (/Assets/Square44x44Logo.png) на вкладке "Визуальные ресурсы" конструктора манифеста пакета приложения.

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

Тема

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

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

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

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

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

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

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

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

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

Важные API