Загрузка изображений и ресурсов, адаптированных по масштабу, теме, высокой контрастности и другим аспектам
Приложение может загружать файлы ресурсов изображения (или другие файлы ресурсов), предназначенные для отображения коэффициента масштабирования, темы, высокой контрастности и других контекстов среды выполнения. На эти изображения можно ссылаться из императивного кода или разметки XAML, например как свойство Source изображения. Они также могут отображаться в исходном файле манифеста пакета приложения ( 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 в документации по 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") следует "://, за которым следует абсолютный путь. В абсолютном пути в начале/ "" путь интерпретируется из корня пакета.
Примечание.
ms-resource Схемы URI (для строковых ресурсов) и ms-appx(-web) (для изображений и других ресурсов) выполняют автоматическое сопоставление квалификатора, чтобы найти ресурс, наиболее подходящий для текущего контекста. ms-appdata Схема URI (которая используется для загрузки данных приложения) не выполняет такого автоматического сопоставления, но вы можете реагировать на содержимое ResourceContext.QualifierValues и явно загружать соответствующие ресурсы из данных приложения с помощью полного физического имени файла в URI. Сведения о данных приложения см. в Магазине и получении параметров и других данных приложения. Схемы веб-URI (например, http, httpsи ftp) не выполняют автоматическое сопоставление. Сведения о том, что делать в этом случае, см. в разделе "Размещение и загрузка образов в облаке".
Абсолютные пути являются хорошим выбором, если файлы изображений остаются там, где они находятся в структуре проекта. Если вы хотите переместить файл изображения, но вы осторожны, что он остается в том же расположении относительно его ссылающегося файла разметки XAML, а не абсолютный путь, который может потребоваться использовать путь, который относится к содержательному файлу разметки. Если это сделать, вам не нужно использовать схему URI. В этом случае вы по-прежнему будете использовать автоматический квалификатор, но только потому, что используется относительный путь в разметке XAML.
<Image Source="Assets/Images/logo.png"/>
Также см . поддержку языка, масштабирования и высокой контрастности плиток и всплывающих элементов.
Ссылка на изображение или другой ресурс из библиотеки классов
Образы и другие ресурсы можно загрузить из проекта библиотеки классов (WinUI 3 в Desktop), ссылаясь на ресурс в URI, использующего схему ms-appx . 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;
}
Обратите внимание, что можно ссылаться на изображения из библиотеки классов как из проекта приложения, так и самого проекта библиотеки классов.
Определение ресурса изображения для целевых объектов
Вы можете использовать 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 (вместо использования по умолчанию), переопределив его значения, а затем используя этот объект контекста в подстановках изображения 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
При работе с ресурсами изображений используются следующие API:
Связанный контент
Windows developer