Работа с изображениями. Элемент Image

Класс Image позволяет выводить изображения. .NET MAUI поддерживает все основные форматы типа png, jpg, gif и svg.

Основные свойства класса Image:

• Aspect: представляет объект типа Aspect, который определяет режим масштабирования изображения.

• IsAnimationPlaying: хранит значение типа bool, определяет будет ли выполняться анимация GIF. По умолчанию равно false, то есть анимация отключена.

• IsLoading: хранит значение типа bool, указывает на статус загрузки изображения. По умолчанию равно false.

• IsOpaque: хранит значение типа bool, указывает, будет ли изображение рассматриваться как прозрачное. По умолчанию значение false.

• Source: хранит значение типа ImageSource, которое определяет источник изображения.

Ключевым свойством является свойство ImageSource, которое представляет объект одноименного класса. Именно это свойство и определяет источник изображения. В качестве источника изображения может использовать локальный файл, файл в интернете, встроенный в приложение ресурс, либо поток. И для использования разных источников в классе ImageSource определен ряд методов:

• FromFile(): возвращает объект типа FileImageSource, который считывает данные из локального файла.

• FromUri(): возвращает объект типа UriImageSource, который считывает данные по определенному адресу Uri.

• FromResource(): возвращает объект типа ResourceImageSource, который считывает данные из ресурса из текущей сборки.

• FromStream(): возвращает объект типа StreamImageSource, который считывает данные изображения из потока.

Рассмотрим различные варианты загрузки изображения.

Загрузка из локального файла

Для упрощения работы с локальными файлами изображений их можно поместить в проект в папку Resources\Images. При добавлении файла в эту папку его свойство Build action автоматически получает значение MauiImage. Такой файл будет автоматически добавляться в пакет приложения. Для управления такими файлами в процессе построения в файле проекта мы можем найти соответствующие элементы:

<Project Sdk="Microsoft.NET.Sdk">

	<!-- Остальное содержимое -->

	<ItemGroup>
		<!-- Остальное содержимое -->
		<!-- Images -->
		<MauiImage Include="Resources\Images\*" />
		<MauiImage Update="Resources\Images\dotnet_bot.svg" BaseSize="168,208" />
	</ItemGroup>
</Project>

здесь элемент

<MauiImage Include="Resources\Images\*" />

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

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

Например, добавим в проект в папку Resources\Images какой-нибудь файл изображения. В моем случае это файл forest.png:

Для загрузки этого файла используем метод ImageSource.FromFile():

namespace HelloApp;

class StartPage : ContentPage
{
    public StartPage()
    {
        Image image = new Image
        {
            Source = ImageSource.FromFile("forest.png")
        };

        Content = image;
    }
}

Также мы можем сократить код:

namespace HelloApp;

class StartPage : ContentPage
{
    public StartPage()
    {
        Image image = new Image { Source = "forest.png" };

        Content = image;
    }
}

В XAML это выглядело бы следующим образом:

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="HelloApp.MainPage">
    <Image Source="forest.png" />
</ContentPage>

Загрузка файла из сети

Для получения изображения из сети применяется метод ImageSource.FromUri(), в который передается сетевой адрес:

Image image = new Image
{
    Source = ImageSource.FromUri(new Uri("https://news.microsoft.com/wp-content/uploads/2014/12/452292672.jpg"))
};

Также можно сократить данный код:

Image image = new Image { Source = "https://news.microsoft.com/wp-content/uploads/2014/12/452292672.jpg" };

На уровне XAML все остается также, только меняется адрес:

<Image Source="https://news.microsoft.com/wp-content/uploads/2014/12/452292672.jpg" />

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

• CacheValidity: объект типа TimeSpan, который определяет продолжительность кэширования. Значение по умолчанию - 1 день.

• CachingEnabled: значение типа bool, которое определяет, будет ли применяться кэширование. Значение по умолчанию - true (то есть кэширование включено).

Пример настройки кэширования в xaml:

<Image>
    <Image.Source>
        <UriImageSource Uri="https://news.microsoft.com/wp-content/uploads/2014/12/452292672.jpg"
                        CacheValidity="2:00:00.0" />
    </Image.Source>
</Image>

В данном случае устанавливается срок кэширования в 2 дня.

Аналогичный пример в коде C#:

Image image = new Image();
image.Source = new UriImageSource
{
    Uri = new Uri("https://news.microsoft.com/wp-content/uploads/2014/12/452292672.jpg"),
    CacheValidity = new TimeSpan(2,0,0,0)
};

Загрузка встроенного ресурса

Встроенные ресурсы изображений встраиваются в сборку и затем могут загружаться с помощью идентификатора данных ресурсов. Например, добавим в корень проекта какой-нибудь файл изображения (в моем случае это файл forest.jpg)

Чтобы обозначит файл как встроенный ресурс, в окне свойств для этого файла для поля Build Action устанавливается значение Embedded resource

Для загрузки встроенного ресурса применяется метод ImageSource.FromResource(), в который передается идентификатор ресурса. Идентификатор состоит из имени проекта и пути к ресурсу внутри данного проекта. Например, выше файл forext.jpng расположен в корне проекта HelloApp, соответственно идентификатором данного ресурса будет HelloApp.forest.jpg. Если бы файл находился бы в проекте в папке Assets/Images, тогда его идентификатором было бы HelloApp.Assets.Images.forest.jpg. Так, в случае выше ресурс изображения будет загружаться следующим образом:

Image image = new Image
{
    Source = ImageSource.FromResource("HelloApp.forest.jpg")
};

Масштабирование изображения

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

• AspectFit: изображение масштабируется с сохранением аспектного отношения между шириной и высотой, но ширина и высота не могут быть больше ширины и высоты Image

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

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

• Center: изображение центрируется по центру и масштабируется с сохранением аспектного отношения между шириной и высотой

Применим эти значения:

namespace HelloApp;

class StartPage : ContentPage
{
    public StartPage()
    {
        Grid grid = new Grid { Padding = 2 };
        grid.RowDefinitions.Add(new RowDefinition { Height = GridLength.Star });
        grid.RowDefinitions.Add(new RowDefinition { Height = GridLength.Star });
        grid.ColumnDefinitions.Add(new ColumnDefinition { Width = GridLength.Star });
        grid.ColumnDefinitions.Add(new ColumnDefinition { Width = GridLength.Star });

        var fileName = "forest.png";
        grid.Add(new Image { Source = fileName, Aspect = Aspect.AspectFit }, 0, 0);
        grid.Add(new Image { Source = fileName, Aspect = Aspect.AspectFill }, 1, 0);
        grid.Add(new Image { Source = fileName, Aspect = Aspect.Fill }, 0,1);
        grid.Add(new Image { Source = fileName, Aspect = Aspect.Center }, 1, 1);
        Content = grid;
    }
}

Применение Aspect в XAML:

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="HelloApp.MainPage">
    <Grid RowDefinitions="*, *" ColumnDefinitions="*, *">
        <Image Source="forest.png" Aspect="AspectFit" />
        <Image Source="forest.png" Aspect="AspectFill" Grid.Column="1" Grid.Row="0" />
        <Image Source="forest.png" Aspect="Fill" Grid.Column="0" Grid.Row="1" />
        <Image Source="forest.png" Aspect="Center"  Grid.Column="1" Grid.Row="1" />
    </Grid>
</ContentPage>