Image в .NET MAUI

Автор:

learn.microsoft

Image в пользовательском интерфейсе многоплатформенного приложения .NET (.NET MAUI) передает изображение, которое можно загрузить из локального файла, URI или потока. Поддерживаются стандартные форматы изображений для платформы, включая анимированные GIF, а также локальные файлы масштабируемой векторной графики (SVG).

Image определяет следующие свойства:

  • Aspect с типом Aspect определяет режим масштабирования изображения.
  • IsAnimationPlaying с типом bool определяет, воспроизводится или остановлен анимированный GIF. По умолчанию это свойство имеет значение false.
  • IsLoading с типом bool указывает на состояние загрузки изображения. По умолчанию это свойство имеет значение false.
  • IsOpaque с типом bool указывает, может ли движок рендеринга рассматривать изображение как непрозрачное при его рендеринге. По умолчанию это свойство имеет значение false.
  • Source с типом ImageSource задает источник изображения.

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

Примечание. Значки шрифтов можно отображать с помощью Image, указав данные значка шрифта в качестве объекта FontImageSource.

Класс ImageSource определяет следующие методы, которые могут быть использованы для загрузки изображения из различных источников:

  • FromFile возвращает FileImageSource, который считывает изображение из локального файла.
  • FromUri возвращает UriImageSource, который загружает и считывает изображение из указанного URI.
  • FromStream возвращает источник StreamImageSource, который считывает изображение из потока, предоставляющего данные об изображении.

В XAML изображения можно загружать из файлов и URI, указывая имя файла или URI в качестве строкового значения для свойства Source.

Важно. Изображения будут отображаться в полном разрешении, если только размер изображения не ограничен его компоновкой или не указано свойство HeightRequest или WidthRequest изображения.

Загрузка локального изображения

Изображения можно добавить в проект приложения, перетащив их в папку Resources\Images проекта, где действие сборки будет автоматически установлено на MauiImage. Во время сборки векторные изображения будут изменены до разрешения, соответствующего целевой платформе и устройству, и добавлены в пакет приложения. Это необходимо, поскольку разные платформы поддерживают различные разрешения изображений, и операционная система выбирает подходящее разрешение изображения во время выполнения программы, основываясь на возможностях устройства.

Чтобы соответствовать правилам именования ресурсов Android, все имена локальных файлов изображений должны быть строчными, начинаться и заканчиваться буквенными символами и содержать только буквенно-цифровые символы или символы подчеркивания.

Важно! .NET MAUI преобразует файлы SVG в файлы PNG. Поэтому при добавлении SVG-файла в проект приложения .NET MAUI на него следует ссылаться из XAML или C# с расширением .png.

Соблюдение этих правил именования и размещения файлов позволяет следующему XAML загружать и отображать изображение:

<Image Source="dotnet_bot.png" />

Эквивалентный код на языке C# имеет вид:

Image image = new Image
{
   Source = ImageSource.FromFile("dotnet_bot.png")
};

Метод ImageSource.FromFile требует строкового аргумента и возвращает новый объект FileImageSource, который считывает изображение из файла. Имеется также оператор неявного преобразования, позволяющий указывать имя файла в качестве строкового аргумента свойства Image.Source:

Image image = new Image { Source = "dotnet_bot.png" };

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

Удаленные изображения можно загружать и отображать, указывая URI в качестве значения свойства Source:

<Image Source="https://aka.ms/campus.jpg" />
Эквивалентный код на языке C# имеет вид:
Image image = new Image
{
   Source = ImageSource.FromUri(new Uri("https://aka.ms/campus.jpg"))
};

Метод ImageSource.FromUri требует аргумента Uri и возвращает новый объект UriImageSource, который считывает изображение из Uri. Также имеется неявное преобразование для строковых URI:

Image image = new Image { Source = "https://aka.ms/campus.jpg" };

Кэширование изображений

По умолчанию включено кэширование загруженных изображений, причем кэшированные изображения хранятся в течение 1 дня. Это поведение можно изменить, задав свойства класса UriImageSource.

Класс UriImageSource определяет следующие свойства:

  • Uri с типом Uri представляет собой URI изображения, загружаемого для отображения.
  • CacheValidity с типом TimeSpan определяет, в течение какого времени изображение будет храниться локально. По умолчанию значение этого свойства равно 1 дню.
  • CachingEnabled с типом bool определяет, включено ли кэширование изображения. По умолчанию значение этого свойства равно true.

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

Чтобы задать конкретный период кэширования, установите свойство Source в объект UriImageSource, в котором задано свойство CacheValidity:

<Image>
   <Image.Source>
       <UriImageSource Uri="https://aka.ms/campus.jpg"
                       CacheValidity="10:00:00:00" />
   </Image.Source>
</Image>

Эквивалентный код на языке C# имеет вид:

Image image = new Image();
image.Source = new UriImageSource
{
   Uri = new Uri("https://aka.ms/campus.jpg"),
   CacheValidity = new TimeSpan(10,0,0,0)
};

В данном примере период кэширования установлен на 10 дней.

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

Изображения можно загружать из потоков с помощью метода ImageSource.FromStream:

Image image = new Image
{
   Source = ImageSource.FromStream(() => stream)
};

Загрузка значка шрифта

Расширение разметки FontImage позволяет отображать значок шрифта в любом представлении, которое может отображать ImageSource. Оно обеспечивает ту же функциональность, что и класс FontImageSource, но с более лаконичным представлением.

Расширение разметки FontImage поддерживается классом FontImageExtension, который определяет следующие свойства:

  • FontFamily типа string – семейство шрифтов, к которому принадлежит пиктограмма шрифта.
  • Glyph типа string – значение символа юникода для пиктограммы шрифта.
  • Color типа Color – цвет, который будет использоваться при отображении значка шрифта.
  • Size типа double – размер в единицах, не зависящих от устройства, отображаемого значка шрифта. По умолчанию значение равно 30. Кроме того, это свойство может быть установлено на именованный размер шрифта.

Примечание. Парсер XAML позволяет сокращать класс FontImageExtension до FontImage.

Свойство Glyph является свойством содержимого класса FontImageExtension. Поэтому для выражений разметки XAML, выраженных фигурными скобками, можно исключить часть выражения Glyph= при условии, что она является первым аргументом.

Следующий пример XAML показывает, как использовать расширение разметки FontImage:

XAML

<Image BackgroundColor="#D1D1D1"
      Source="{FontImage &#xf30c;, FontFamily=Ionicons, Size=44}" />

В данном примере сокращенная версия имени класса FontImageExtension используется для отображения в Image значка XBox из семейства шрифтов Ionicons:

Хотя символ юникода для пиктограммы - \uf30c, в XAML он должен быть экранирован и становится &#xf30c;.

Загрузка анимированных GIF-файлов

В .NET MAUI реализована поддержка отображения небольших анимированных GIF-файлов. Это достигается путем установки свойства Source в анимированный GIF-файл:

<Image Source="demo.gif" />

Важно. Хотя поддержка анимированных GIF в .NET MAUI включает возможность загрузки файлов, она не поддерживает кэширование или потоковую передачу анимированных GIF.

По умолчанию при загрузке анимированного GIF-файла он не будет воспроизводиться. Это связано с тем, что свойство IsAnimationPlaying, определяющее, воспроизводится или остановлен анимированный GIF, по умолчанию имеет значение false. Поэтому при загрузке анимированного GIF-файла он не будет воспроизводиться до тех пор, пока свойство IsAnimationPlaying не будет установлено в true. Воспроизведение можно остановить, сбросив значение свойства IsAnimationPlaying в false. Обратите внимание, что данное свойство не влияет на отображение источника изображения, не являющегося GIF.

Управление масштабированием изображения

Свойство Aspect определяет способ масштабирования изображения в соответствии с областью отображения и должно быть установлено на один из членов перечисления Aspect:

  • AspectFit – буквенная рамка (если требуется), чтобы изображение целиком помещалось в область отображения, с добавлением пустого пространства сверху, снизу или по бокам в зависимости от ширины или высоты изображения.
  • AspectFill – обрезает изображение так, чтобы оно заполнило область экрана с сохранением соотношения сторон.
  • Fill – растягивает изображение, чтобы оно полностью и точно заполнило область дисплея. Это может привести к искажению изображения.
  • Center – центрирует изображение в области дисплея с сохранением соотношения сторон.

Материалы по теме