通过

图片

  • 项目

.NET 多平台应用 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 对象。 还有一个隐式转换运算符，它允许将文件名指定为 string 参数 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 参数，并返回从 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 属性设置为 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)
};

重要

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

加载字体图标

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

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

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

注意

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

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

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

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

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

FontImage 标记扩展的屏幕截图。

虽然图标的unicode字符是\uf30c，但在XAML中必须转义为&#xf30c;。

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

可以通过在 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 - 在保留纵横比的同时将图像居中显示区域。