Изображения в Xamarin.Forms

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

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

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

Отображение изображений

Xamarin.FormsImage использует представление для отображения изображений на странице. У него есть несколько важных свойств:

• SourceImageSource— экземпляр, файл, URI или ресурс, который задает изображение для отображения.
• Aspect — Как размер изображения в границах, в которых он отображается (следует ли растянуть, обрезку или почтовое поле).

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

• FromFile — требуется имя файла или путь к файлу, которые можно разрешить на каждой платформе.
• FromUri — требуется объект URI, например. new Uri("http://server.com/image.jpg") .
• FromResource — требуется идентификатор ресурса для файла изображения, внедренного в проект библиотеки приложения или .NET Standard, с действием сборки:EmbeddedResource.
• FromStream — требуется поток, предоставляющий данные изображения.

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

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

Изображения можно загружать из локального файла, внедренного ресурса, скачиваемого или загружаемого из потока. Кроме того, значки шрифта можно отобразить в Image представлении, указав данные значка шрифта в объекте FontImageSource . Дополнительные сведения см. в руководстве по шрифтам для отображения значков шрифтов.

Локальные образы

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

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

• iOS — предпочтительный способ управления и поддержки образов, так как iOS 9 — использовать наборы образов каталога активов, которые должны содержать все версии образа, необходимые для поддержки различных устройств и коэффициентов масштабирования для приложения. Дополнительные сведения см. в разделе "Добавление изображений в набор образов каталога активов".
• Android — размещение изображений в каталоге Resources/drawable с помощью действия сборки: AndroidResource. Кроме того, можно предоставлять версии изображения с высоким и низким уровнем DPI (в соответствующих подкаталогах ресурсов, таких как drawable-ldpi, drawable-hdpi и drawable-xhdpi).
• универсальная платформа Windows (UWP) — по умолчанию изображения должны размещаться в корневом каталоге приложения с действием сборки: содержимое. Кроме того, изображения можно поместить в другой каталог, который затем указан с помощью конкретной платформы. Дополнительные сведения см . в каталоге образов по умолчанию в Windows.

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

<Image Source="waterfront.jpg" />

Эквивалентный код C# выглядит следующим образом:

var image = new Image { Source = "waterfront.jpg" };

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

Для повышения гибкости Device.RuntimePlatform свойства можно использовать для выбора другого файла изображения или пути для некоторых или всех платформ, как показано в этом примере кода:

image.Source = Device.RuntimePlatform == Device.Android
                ? ImageSource.FromFile("waterfront.jpg")
                : ImageSource.FromFile("Images/waterfront.jpg");

Собственные разрешения (сетчатка и высокий DPI)

IOS, Android и UWP включают поддержку различных разрешений изображений, где операционная система выбирает соответствующий образ во время выполнения на основе возможностей устройства. Xamarin.Forms использует API собственных платформ для загрузки локальных образов, поэтому он автоматически поддерживает альтернативные разрешения, если файлы правильно именуются и находятся в проекте.

Предпочтительный способ управления изображениями, так как iOS 9 — перетаскивать изображения для каждого разрешения, необходимого для соответствующего набора образов каталога активов. Дополнительные сведения см. в разделе "Добавление изображений в набор образов каталога активов".

До iOS 9 версии изображения сетчатки можно поместить в папку Resources — два и три раза разрешение с помощью @2x или @3x суффиксов в имени файла до расширения файла (например). [email protected] Однако этот метод работы с изображениями в приложении iOS не рекомендуется apple. Дополнительные сведения см. в разделе "Размеры изображений" и "Имена файлов".

Изображения альтернативного разрешения Android должны размещаться в специально именованных каталогах в проекте Android, как показано на следующем снимке экрана:

Имена файлов образа UWP можно суффиксировать перед .scale-xxx расширением файла, где xxx процент масштабирования применяется к ресурсу, например myimage.scale-200.png. Затем изображения можно ссылаться на код или XAML без модификатора масштабирования, например только myimage.png. Платформа выберет ближайшее соответствующее масштабирование активов на основе текущего DPI дисплея.

Дополнительные элементы управления, отображающие изображения

Некоторые элементы управления имеют свойства, отображающие изображение, например:

• Button имеет свойство, которое можно задать на ImageSource растровое изображение, которое будет отображаться на экране Button. Дополнительные сведения см. в разделе "Использование растровых карт с кнопками".

• ImageButtonSource имеет свойство, которое можно задать для отображения в изображенииImageButton. Дополнительные сведения см. в разделе "Настройка источника изображения".

• ToolbarItemIconImageSource имеет свойство, которое можно задать для образа, загруженного из файла, внедренного ресурса, URI или потока.

• ImageCellImageSource имеет свойство, которое можно задать для изображения, полученного из файла, внедренного ресурса, URI или потока.

• Page. Любой тип страницы, производный от Page имеющих IconImageSource и BackgroundImageSource свойств, которые можно назначить файл, внедренный ресурс, URI или поток. В определенных обстоятельствах, например при NavigationPage отображении ContentPageзначка, будет отображаться, если она поддерживается платформой.

  Внимание

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

Внедренные образы

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

Чтобы внедрить изображение в проект, щелкните правой кнопкой мыши, чтобы добавить новые элементы и выберите нужный образ. По умолчанию изображение будет иметь действие сборки: нет. Для этого необходимо задать действие сборки: EmbeddedResource.

Если вы помещаете внедренные изображения в папки в проекте, имена папок также разделяются точками (.) в идентификаторе ресурса. Перемещение изображения beach.jpg в папку с именем MyImages приведет к идентификатору ресурса WorkingWithImages.MyImages.beach.jpg

Код для загрузки внедренного образа просто передает идентификатор ресурса методу ImageSource.FromResource , как показано ниже:

Image embeddedImage = new Image
{
    Source = ImageSource.FromResource("WorkingWithImages.beach.jpg", typeof(MyClass).GetTypeInfo().Assembly)
};

В настоящее время для идентификаторов ресурсов нет неявного преобразования. Вместо этого необходимо использовать ImageSource.FromResource или new ResourceImageSource() загружать внедренные образы.

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

XAML

Так как встроенный преобразователь типов в string ResourceImageSourceне существует, эти типы изображений не могут быть загружены в машинном коде XAML. Вместо этого можно записать простое расширение разметки XAML для загрузки изображений с помощью идентификатора ресурса, указанного в XAML:

[ContentProperty (nameof(Source))]
public class ImageResourceExtension : IMarkupExtension
{
 public string Source { get; set; }

 public object ProvideValue (IServiceProvider serviceProvider)
 {
   if (Source == null)
   {
     return null;
   }

   // Do your translation lookup here, using whatever method you require
   var imageSource = ImageSource.FromResource(Source, typeof(ImageResourceExtension).GetTypeInfo().Assembly);

   return imageSource;
 }
}

Чтобы использовать это расширение, добавьте настраиваемого xmlns в XAML, используя правильные значения пространства имен и сборок для проекта. Затем источник изображения можно задать с помощью следующего синтаксиса: {local:ImageResource WorkingWithImages.beach.jpg} Ниже показан полный пример XAML:

<?xml version="1.0" encoding="UTF-8" ?>
<ContentPage
   xmlns="http://xamarin.com/schemas/2014/forms"
   xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
   xmlns:local="clr-namespace:WorkingWithImages;assembly=WorkingWithImages"
   x:Class="WorkingWithImages.EmbeddedImagesXaml">
 <StackLayout VerticalOptions="Center" HorizontalOptions="Center">
   <!-- use a custom Markup Extension -->
   <Image Source="{local:ImageResource WorkingWithImages.beach.jpg}" />
 </StackLayout>
</ContentPage>

Устранение неполадок внедренных образов

Отладка кода

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

using System.Reflection;
// ...
// NOTE: use for debugging, not in released app code!
var assembly = typeof(MyClass).GetTypeInfo().Assembly;
foreach (var res in assembly.GetManifestResourceNames())
{
    System.Diagnostics.Debug.WriteLine("found resource: " + res);
}

Изображения, внедренные в другие проекты

По умолчанию метод ищет только изображения в той же сборке, ImageSource.FromResource что и код, вызывающий ImageSource.FromResource метод. Используя приведенный выше код отладки, можно определить, какие сборки содержат определенный ресурс, изменив typeof() оператор на известный для каждой Type сборки.

Однако исходная сборка, на которой выполняется поиск внедренного образа, может быть указана в качестве аргумента ImageSource.FromResource метода:

var imageSource = ImageSource.FromResource("filename.png",
            typeof(MyClass).GetTypeInfo().Assembly);

Скачивание изображений

Изображения можно скачать автоматически для отображения, как показано в следующем XAML:

<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
       xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
       x:Class="WorkingWithImages.DownloadImagesXaml">
  <StackLayout VerticalOptions="Center" HorizontalOptions="Center">
    <Label Text="Image UriSource Xaml" />
    <Image Source="https://aka.ms/campus.jpg" />
    <Label Text="campus.jpg gets downloaded from microsoft.com" />
  </StackLayout>
</ContentPage>

Эквивалентный код C# выглядит следующим образом:

var webImage = new Image {
     Source = ImageSource.FromUri(
        new Uri("https://aka.ms/campus.jpg")
     ) };

Для ImageSource.FromUri метода требуется Uri объект и возвращается новый UriImageSource объект, который считывается из объекта Uri.

Существует также неявное преобразование строк URI, поэтому следующий пример также будет работать:

webImage.Source = "https://aka.ms/campus.jpg";

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

Скачанный кэширование изображений

Также поддерживает UriImageSource кэширование скачанных образов, настроенных с помощью следующих свойств:

• CachingEnabled — включена ли кэширование (true по умолчанию).
• CacheValidity — Определяет TimeSpan , сколько времени образ будет храниться локально.

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

image.Source = new UriImageSource { CachingEnabled = false, Uri = new Uri("https://server.com/image") };

Чтобы задать определенный период кэша (например, 5 дней), создайте экземпляр источника образа следующим образом:

webImage.Source = new UriImageSource
{
    Uri = new Uri("https://aka.ms/campus.jpg"),
    CachingEnabled = true,
    CacheValidity = new TimeSpan(5,0,0,0)
};

Встроенное кэширование упрощает поддержку таких сценариев, как прокрутка списков изображений, где можно задать (или привязать) изображение в каждой ячейке и позволить встроенному кэшу повторно загружать изображение, когда ячейка прокручивается обратно в представление.

Анимированные GIF-файлы

Xamarin.Forms включает поддержку отображения небольших анимированных GIF-файлов. Это достигается путем установки Image.Source свойства в анимированный GIF-файл:

<Image Source="demo.gif" />

По умолчанию при загрузке анимированного GIF-файла он не будет воспроизводиться. Это связано с тем, что IsAnimationPlaying свойство, которое определяет, воспроизводит ли анимированный GIF-файл или останавливается, имеет значение falseпо умолчанию. Это свойство типа boolподдерживается BindableProperty объектом, что означает, что он может быть целевым объектом привязки данных и стилем.

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

Значки и экраны-заставки

Хотя и не связаны с Image представлением, значки приложений и экраны-заставки также важны для использования изображений в Xamarin.Forms проектах.

Настройка значков и экранов-заставок для Xamarin.Forms приложений выполняется в каждом из проектов приложений. Это означает создание правильного размера изображений для iOS, Android и UWP. Эти изображения должны быть названы и расположены в соответствии с требованиями каждой платформы.

Значки

Дополнительные сведения о создании этих ресурсов приложений см. в руководствах по работе с изображениями, Google Iconography и UWP для ресурсов плиток и значков.

Кроме того, значки шрифта можно отобразить в Image представлении, указав данные значка шрифта в объекте FontImageSource . Дополнительные сведения см. в руководстве по шрифтам для отображения значков шрифтов.

Экраны-заставки

Только для приложений iOS и UWP требуется экран-заставка (также называемый начальным экраном или изображением по умолчанию).

Ознакомьтесь с документацией по iOS, работающей с изображениями и экранами-заставкой на Центр разработки Windows.

Дополнительные ссылки

• Работа с изображениями iOS
• Значок Android
• Руководство по работе с ресурсами плиток и значков