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

Ваше приложение может загружать файлы ресурсов изображения (или другие файлы ресурсов), адаптированные для коэффициента масштабированиядисплея , темы, высокой контрастности и других контекстов выполнения. Эти изображения можно использовать в императивном коде или в разметке 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"/>

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

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"/>

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

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

Вы можете использовать квалификаторы 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.GetForCurrentView) содержит значение квалификатора для каждого имени квалификатора, представляющего контекст среды выполнения по умолчанию (другими словами, параметры текущего пользователя и компьютера). Файлы изображений сопоставляются на основе квалификаторов в их именах со значениями квалификатора в контексте среды выполнения.

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

Это можно сделать, создав новый ResourceContext (вместо по умолчанию используемого), переопределив его значения, а затем используя этот объект контекста при поиске изображений.

var resourceContext = new Windows.ApplicationModel.Resources.Core.ResourceContext(); // not using ResourceContext.GetForCurrentView 
resourceContext.QualifierValues["Contrast"] = "high";
var namedResource = Windows.ApplicationModel.Resources.Core.ResourceManager.Current.MainResourceMap[@"Files/Assets/Logo.png"];
var resourceCandidate = namedResource.Resolve(resourceContext);
var imageFileStream = resourceCandidate.GetValueAsStreamAsync().GetResults();
var bitmapImage = new Windows.UI.Xaml.Media.Imaging.BitmapImage();
bitmapImage.SetSourceAsync(imageFileStream);
this.myXAMLImageElement.Source = bitmapImage;

Чтобы добиться того же эффекта на глобальном уровне, можно переопределить значения квалификатора в ResourceContext по умолчанию. Но вместо этого мы советуем вызывать ResourceContext.SetGlobalQualifierValue. Значения задаются один раз при вызове SetGlobalQualifierValue, а затем эти значения применяются по умолчанию к ResourceContext при каждом его использовании для поиска. По умолчанию класс ResourceManager использует ресурсный контекст .

Windows.ApplicationModel.Resources.Core.ResourceContext.SetGlobalQualifierValue("Contrast", "high");
var namedResource = Windows.ApplicationModel.Resources.Core.ResourceManager.Current.MainResourceMap[@"Files/Assets/Logo.png"];
this.myXAMLImageElement.Source = new Windows.UI.Xaml.Media.Imaging.BitmapImage(namedResource.Uri);

Обновление изображений в ответ на события изменения значения квалификатора

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

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

public MainPage()
{
    this.InitializeComponent();

    ...

    // Subscribe to the event that's raised when a qualifier value changes.
    var qualifierValues = Windows.ApplicationModel.Resources.Core.ResourceContext.GetForCurrentView().QualifierValues;
    qualifierValues.MapChanged += new Windows.Foundation.Collections.MapChangedEventHandler<string, string>(QualifierValues_MapChanged);
}

private async void QualifierValues_MapChanged(IObservableMap<string, string> sender, IMapChangedEventArgs<string> @event)
{
    var dispatcher = this.myImageXAMLElement.Dispatcher;
    if (dispatcher.HasThreadAccess)
    {
        this.RefreshUIImages();
    }
    else
    {
        await dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () => this.RefreshUIImages());
    }
}

private void RefreshUIImages()
{
    var namedResource = Windows.ApplicationModel.Resources.Core.ResourceManager.Current.MainResourceMap[@"Files/Assets/Logo.png"];
    this.myImageXAMLElement.Source = new Windows.UI.Xaml.Media.Imaging.BitmapImage(namedResource.Uri);
}

Важные API

• Контекст ресурса
• ResourceContext.SetGlobalQualifierValue
• MapChanged

Связанные темы

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