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

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

  • Статья

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

Ресурс изображения содержится в файле ресурсов изображений. Также можно представить себе изображение в качестве ресурса, а содержащий его файл — в качестве файла ресурса; и эти файлы ресурсов находятся в папке \Assets вашего проекта. Общие сведения об использовании квалификаторов в именах файлов ресурсов изображений приводятся в разделе Адаптация ресурсов для языка, масштаба и других квалификаторов.

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

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

По умолчанию для квалификатора scale используется значение scale-100. Таким образом, эти два варианта эквивалентны (они предоставляют изображение в масштабе 100, то есть с коэффициентом масштабирования 1).

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

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

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

В следующем примере показано, как можно предоставить варианты ресурса изображения с именем /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"/>

Обратите внимание, что вы используете схему URI ms-appx, так как ссылаетесь на файл, который поступает из пакета приложения. См. схемы 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, но в разделе web.

<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) следует ://, а далее указан абсолютный путь. В абсолютном пути начальный символ / обеспечивает его интерпретацию из корневого каталога пакета.

Примечание

Схемы ms-resource URI (для строковых ресурсов) и ms-appx(-web) (для изображений и других ресурсов) выполняют автоматическое сопоставление квалификатора для поиска ресурса, наиболее подходящего для текущего контекста. Схема URI ms-appdata (которая используется для загрузки данных приложения) не выполняет никакое автоматическое сопоставление, но вы можете реагировать на содержимое ResourceContext.QualifierValues и явно загружать соответствующие ресурсы из данных приложения, используя полное имя физического файла в URI. Подробнее о данных приложения: Хранение и извлечение параметров и прочих данных приложения. Веб-схемы URI (например, http, https и ftp) также не выполняют автоматическое сопоставление. Сведения о том, что делать в этом случае, см. в разделе Размещение и загрузка изображений в облаке.

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

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

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

Квалификация ресурса изображения по 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.

Добавление ресурса (английский язык)

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

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

См. раздел Зеркальное отображение изображений.

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

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

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

См. также раздел