Загрузка изображений и ресурсов, адаптированных по масштабу, теме, высокой контрастности и другим аспектам

Приложение может загружать файлы ресурсов изображения (или другие файлы ресурсов), предназначенные для коэффициента масштабирования, темы, высокой контрастности и других контекстов среды выполнения. На эти изображения можно ссылаться из императивного кода или разметки XAML, например как свойство Source изображения. Они также могут отображаться в исходном файле манифеста пакета приложения (файл Package.appxmanifest), например, в качестве значения для значка приложения на вкладке "Визуальные ресурсы" конструктора манифестов Visual Studio, а также на плитках и уведомлениях. Используя квалификаторы в именах файлов изображений и при необходимости динамически загружая их с помощью ResourceContext, можно загрузить наиболее подходящий файл изображения, который лучше всего соответствует параметрам среды выполнения пользователя для масштабирования, темы, высокой контрастности, языка и других контекстов.

Ресурс изображения содержится в файле ресурса изображения. Вы также можете рассматривать изображение как ресурс и файл, содержащий его как файл ресурса; и эти типы файлов ресурсов можно найти в папке \Assets проекта. Сведения о том, как использовать квалификаторы в именах файлов ресурсов изображения, см. в статье "Настройка ресурсов для языка, масштабирования и других квалификаторов".

Ниже приведены некоторые распространенные квалификаторы для изображений:

• scale
• тема
• контраст
• размер цели

Оценка ресурса изображения по масштабу, теме и контрасту

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

В следующем примере показано, как указать варианты ресурса изображения с именем /Assets/Images/logo.pngдля различных параметров шкалы отображения, темы и высокой контрастности с помощью именования папок.

\Assets\Images\contrast-standard\theme-dark
    \scale-100\logo.png
    \scale-200\logo.png
\Assets\Images\contrast-standard\theme-light
    \scale-100\logo.png
    \scale-200\logo.png
\Assets\Images\contrast-high
    \scale-100\logo.png
    \scale-200\logo.png

Ссылка на изображение или другой ресурс из разметки XAML и кода

Имя (или идентификатор) ресурса изображения — это его путь и имя файла без всех квалификаторов. Если вы называете папки и/или файлы так же, как в любом из примеров в предыдущем разделе, то у вас есть единый ресурс изображения, и его имя (как абсолютный путь) — это /Assets/Images/logo.png. Вот как вы используете это имя в разметке XAML.

<Image x:Name="myXAMLImageElement" Source="ms-appx:///Assets/Images/logo.png"/>

Обратите внимание, что вы используете схему ms-appx URI, так как вы ссылаетесь на файл, поступающий из пакета приложения. См. схемы URI в документации для UWP. Вот как вы ссылаетесь на тот же ресурс изображения в императивном коде.

this.myXAMLImageElement.Source = new BitmapImage(new Uri("ms-appx:///Assets/Images/logo.png"));

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

var uri = new System.Uri("ms-appx:///Assets/anyAsset.ext");
var storagefile = await Windows.Storage.StorageFile.GetFileFromApplicationUriAsync(uri);

Схема ms-appx-web обращается к тем же файлам, что и ms-appx, но в веб-среде.

<WebView x:Name="myXAMLWebViewElement" Source="ms-appx-web:///Pages/default.html"/>

this.myXAMLWebViewElement.Source = new Uri("ms-appx-web:///Pages/default.html");

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

Обратите внимание, как в этих примерах URI схема ("ms-appx" или "ms-appx-web") следует за "://", после которого идет абсолютный путь. В абсолютном пути в начале "/" путь трактуется из корня пакета.

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

<Image Source="Assets/Images/logo.png"/>

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

Ссылка на изображение или другой ресурс из библиотеки классов

Образы и другие ресурсы можно загрузить из проекта библиотеки классов (WinUI в Desktop), ссылаясь на ресурс в URI, использующем схему . URI должен содержать имя проекта библиотеки классов и путь к ресурсу в проекте библиотеки классов. Например, если у вас есть проект библиотеки классов с именем MyClassLibrary , содержащий изображение с именем logo.png в папке с именем Assets, можно ссылаться на изображение в проекте приложения следующим образом:

<Image Source="ms-appx:///MyClassLibrary/Assets/logo.png"/>

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

private async Task<DateTimeOffset> GetLogoCreatedDateAsync()
{
    Uri uri = new($"ms-appx:///MyClassLibrary/Assets/logo.png");
    Windows.Storage.StorageFile file =
        await Windows.Storage.StorageFile.GetFileFromApplicationUriAsync(uri);

    return file.DateCreated;
}

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

Определение ресурса изображения для параметра targetsize.

Вы можете использовать квалификаторы scale и targetsize для разных вариантов одного изображения, но вы не можете использовать их на одном варианте изображения. Кроме того, необходимо определить по крайней targetsize мере один вариант без квалификатора. Этот вариант должен либо определить значение для scale, либо разрешить ему значение по умолчанию scale-100. Таким образом, эти два варианта /Assets/Square44x44Logo.png ресурса допустимы.

\Assets\Square44x44Logo.scale-200.png
\Assets\Square44x44Logo.targetsize-24.png

И эти два варианта допустимы.

\Assets\Square44x44Logo.png // defaults to scale-100
\Assets\Square44x44Logo.targetsize-24.png

Но этот вариант недопустим.

\Assets\Square44x44Logo.scale-200_targetsize-24.png

Ознакомьтесь с файлом изображения из манифеста пакета приложения

Если вы назовете папки и (или) файлы, как в одном из двух допустимых примеров в предыдущем разделе, у вас будет один ресурс изображения значка приложения, и его имя (как относительный путь) будет Assets\Square44x44Logo.png. В манифесте пакета приложения просто обратитесь к ресурсу по имени. Нет необходимости использовать любую схему URI.

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

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

См. отражение изображений.

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

Можно переопределить ResourceContext по умолчанию, чтобы четко указать, какое значение квалификатора использовать при загрузке изображения. Например, вам может потребоваться управлять именно тем, когда и какие изображения высокой контрастности загружаются. Сведения о том, как работает ResourceContext, см. Определите выбор ресурсов с помощью ResourceContext. Аналогичный пример использования строковых ресурсов см. в разделе "Загрузка строки" для определенного языка или другого контекста.

Создайте новый ResourceContext, переопределите его значения, а затем используйте этот объект контекста для поиска изображений в ResourceMap с помощью GetValue или TryGetValue.

var resourceManager = new Microsoft.Windows.ApplicationModel.Resources.ResourceManager();
var resourceContext = resourceManager.CreateResourceContext();
resourceContext.QualifierValues["Contrast"] = "high";
var resourceMap = resourceManager.MainResourceMap;
var namedResource = resourceMap.TryGetValue(@"Files/Assets/Logo.png", resourceContext);
var imageFileBytes = namedResource.ValueAsBytes;

using (var ms = new InMemoryRandomAccessStream())
{
    using (var writer = new DataWriter(ms.GetOutputStreamAt(0)))
    {
        writer.WriteBytes(imageFileBytes);
        writer.StoreAsync().GetResults();
    }
    var image = new BitmapImage();
    image.SetSource(ms);
    this.myXAMLImageElement.Source = image;
}

По умолчанию класс ResourceManager использует ResourceContext.

Важные API

• ResourceContext
• ResourceMap

Связанный контент

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