通过

Image

  • 项目

.NET Multi-platform App UI (.NET MAUI) Image 显示可从本地文件、URI 或流加载的图像。 支持动画 GIF 等标准平台图像格式，还支持本地可缩放矢量图形 (SVG) 文件。 有关将图像添加到 .NET MAUI 应用项目的详细信息，请参阅将图像添加到 .NET MAUI 应用项目。

Image 定义以下属性:

  • Aspect，类型为 Aspect，定义图像的缩放模式。
  • IsAnimationPlaying，类型为 bool，确定动画 GIF 正在播放还是已停止。 此属性的默认值为 false。
  • IsLoading，类型为 bool，指示图像的加载状态。 此属性的默认值为 false。
  • IsOpaque，类型为 bool，指示呈现引擎在呈现图像时是否将图像视为不透明。 此属性的默认值为 false。
  • Source，类型为 ImageSource，指定图像的源。

这些属性由 BindableProperty 对象提供支持；也就是说，它们可以进行样式设置，并且可以作为数据绑定的目标。

注意

可以通过将字体图标数据指定为 FontImageSource 对象来通过 Image 显示字体图标。 有关详细信息，请参阅显示字体图标。

ImageSource 类定义以下可用于从不同源加载图像的方法：

  • FromFile 返回从本地文件读取图像的 FileImageSource。
  • FromUri 返回从指定 URI 下载和读取图像的 UriImageSource。
  • FromStream 返回从提供图像数据的流中读取图像的 StreamImageSource。

在 XAML 中，可以通过将文件名或 URI 指定为 Source 属性的字符串值，从文件和 URI 加载图像。 还可以通过自定义标记扩展从 XAML 中的流加载图像。

重要

除非 Image 的大小受其布局限制，或者指定了 Image 的 HeightRequest 或 WidthRequest 属性，否则图像将以全分辨率显示。

有关向应用添加应用图标和初始屏幕的信息，请参阅应用图标和初始屏幕。

加载本地图像

可以通过将图像拖动到项目的 Resources\Images 文件夹，将其添加到应用项目，其生成操作将自动设置为 MauiImage。 在生成时，矢量图像的大小将调整为目标平台和设备的正确分辨率，并添加到应用包。 此操作必不可少，因为不同的平台支持不同的图像分辨率，并且操作系统在运行时会根据设备的功能选择合适的图像分辨率。

要遵守 Android 资源命名规则，所有本地图像文件名必须为小写、以字母字符开头和结尾，并且仅包含字母数字字符或下划线。 有关详细信息，请参阅 developer.android.com 上的应用资源概述。

重要

.NET MAUI 可将 SVG 文件转换为 PNG 文件。 因此，将 SVG 文件添加到 .NET MAUI 应用项目时，应从具有 .png 扩展名的 XAML 或 C# 引用该文件。

遵循这些文件命名和放置规则使以下 XAML 能够加载和显示图像：

<Image Source="dotnet_bot.png" />

等效 C# 代码如下：

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

ImageSource.FromFile 方法需要 string 参数，并返回从文件读取图像的新 FileImageSource 对象。 还有一个隐式转换运算符，它允许将文件名指定为 Image.Source 属性的 string 参数：

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 参数，并返回从 Uri 读取图像的新 UriImageSource 对象。 还有针对基于字符串的 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 属性设置为设置其 CacheValidity 属性的 UriImageSource 对象：

<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)
};

重要

在 Android 上使用 ImageSource.FromStream 方法从流加载图像时禁用图像缓存。 这是由于缺少用于创建合理缓存密钥的数据。

加载字体图标

FontImage 标记扩展支持在任何可以显示 ImageSource 的视图中显示字体图标。 它提供与 FontImageSource 类相同的功能，但表示形式更简洁。

FontImageExtension 类支持 FontImage 标记扩展，并定义以下属性：

  • FontFamily，类型为 string，字体图标所属的字体系列。
  • Glyph，类型为 string，字体图标的 Unicode 字符值。
  • Color，类型为 Color，显示字体图标时要使用的颜色。
  • Size，类型为 double，呈现字体图标的大小（单位与设备无关）。 默认值为 30。 此外，此属性可以设置为命名字体大小。

注意

XAML 分析程序允许将 FontImageExtension 类缩写为 FontImage。

Glyph 属性是 FontImageExtension 的内容属性。 因此，对于用大括号表示的 XAML 标记表达式，如果它是第一个参数，则可以删除表达式的 Glyph= 部分。

以下 XAML 示例显示了如何使用 FontImage 标记扩展：

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

在此示例中，FontImageExtension 类名的缩写版本用于在 Image 中显示 Ionicons 字体系列中的 XBox 图标：

Screenshot of the FontImage markup extension.

虽然图标的 Unicode 字符为 \uf30c，但它必须在 XAML 中转义，因此变为 &#xf30c;。

有关通过在 FontImageSource 对象中指定字体图标数据来显示字体图标的信息，请参阅显示字体图标。

加载动画 GIF

.NET MAUI 包括对显示小型动画 GIF 的支持。 可以通过将 Source 属性设置为动画 GIF 文件来实现此目的：

<Image Source="demo.gif" />

重要

虽然 .NET MAUI 中的动画 GIF 支持包括下载文件的功能，但它不支持缓存或流式处理动画 GIF。

默认情况下，动画 GIF 在加载时不会播放。 这是因为，IsAnimationPlaying 属性控制动画 GIF 是播放还是停止，其默认值为 false。 因此，加载动画 GIF 时，除非将 IsAnimationPlaying 属性设置为 true，否则不会播放该动画。 可以通过将 IsAnimationPlaying 属性重置为 false 来停止播放。 请注意，此属性在显示非 GIF 图像源时不起作用。

控制图像缩放

Aspect 属性确定如何缩放图像以适合显示区域，并应设置为 Aspect 枚举的其中一个成员：

  • AspectFit - 对图像上下加框（如需要），以使整个图像适合显示区域，并根据图像的宽度或高度，在顶部/底部或侧边添加空白区域。
  • AspectFill - 剪裁图像，使其填充显示区域，同时保持纵横比。
  • Fill - 拉伸图像，以完全、准确填充显示区域。 这可能会导致图像失真。
  • Center - 将图像在显示区域居中显示，同时保持纵横比。