通过

图像和图像画笔

  • 项目

若要显示图像，可以使用 Image 对象或 ImageBrush 对象。 Image 对象呈现图像，ImageBrush 对象使用图像绘制另一个对象。

这些元素是正确的吗？

使用 Image 元素在应用中显示独立图像。

使用 ImageBrush 将图像应用到另一个对象。 ImageBrush 的用途包括文本的装饰效果，或控件或布局容器的背景。

UWP 和 WinUI 2

重要

本文中的信息和示例是针对使用 Windows App SDK 和 WinUI 3 的应用优化的，但通常适用于使用 WinUI 2 的 UWP 应用。 有关特定于平台的信息和示例，请查看 UWP API 参考。

本部分包含在 UWP 或 WinUI 2 应用中使用该控件所需的信息。

此控件的 API 存在于 Windows.UI.Xaml.Controls 和 Windows.UI.Xaml.Media 命名空间中。

建议使用最新的 WinUI 2 来获取所有控件的最新样式和模板。

从 Windows 10 版本 1607 开始， Image 元素支持动态 GIF 图像。 使用 BitmapImage 作为图像源时，可以访问 BitmapImage API 来控制动态 GIF 图像的播放。 有关详细信息，请参阅 BitmapImage 类页上的“备注”。

注意

为 Windows 10 版本 1607 编译应用并在版本 1607（或更高版本）上运行时，可以使用动态 GIF 支持。 在为以前版本编译或运行应用时，将显示 GIF 的第一帧，但不进行动画处理。

创建映像

打开 WinUI 3 库应用并查看 ImageBrushes 的操作。

WinUI 3 库应用包括大多数 WinUI 3 控件、特性和功能的交互式示例。 通过 Microsoft Store 获取应用，或在 GitHub 上获取源代码

映像

此示例演示如何使用 Image 对象创建映像。

<Image Width="200" Source="sunset.jpg" />

下面是呈现的图像对象。

图像元素示例

在此示例中， Source 属性指定要显示的图像的位置。 可以通过指定绝对 URL（例如 http://contoso.com/myPicture.jpg）或指定相对于你的应用包装结构的 URL 来设置 Source。 在本示例中，我们将“sunset.jpg”图像文件放在项目的根文件夹中，并声明将包含图像文件的项目设置作为内容。

ImageBrush

使用 ImageBrush 对象，可以使用图像绘制采用 Brush 对象的区域。 例如，你可将 ImageBrush 用于 Ellipse 的 Fill 属性或 Canvas 的 Background 属性的值。

下一个示例演示如何使用 ImageBrush 绘制椭圆。

<Ellipse Height="200" Width="300">
   <Ellipse.Fill>
     <ImageBrush ImageSource="sunset.jpg" />
   </Ellipse.Fill>
</Ellipse>

下面是 ImageBrush 绘制的椭圆。

ImageBrush 绘制的椭圆。

拉伸图像

如果你没有设置 Image 的 Width 或 Height 值，将以 Source 指定的图像的尺寸显示。 设置 Width 和 Height 将创建一个包含的矩形区域，在其中显示图像。 可以使用 Stretch 属性指定图像如何填充此包含区域。 Stretch 属性接受 Stretch 枚举定义的以下值：

  • 无：图像不会拉伸以填充输出维度。 请谨慎使用此 Stretch 设置：如果源图像大于包含区域，则图像将被剪裁，这通常是不需要的，因为你对视区没有任何控制，就像你对故意 剪辑一样。
  • 统一：缩放图像以适应输出维度。 但保留内容的纵横比。 这是默认值。
  • UniformToFill：缩放图像，使其完全填充输出区域，但保留其原始纵横比。
  • 填充：缩放图像以适应输出尺寸。 由于内容的高度和宽度是独立缩放的，因此可能不会保留图像的原始纵横比。 也就是说，图像可能会扭曲以完全填充输出区域。

拉伸设置的示例。

裁剪图像

可以使用 Clip 属性从图像输出中剪辑区域。 将 Clip 属性设置为 Geometry。 目前不支持非矩形剪辑。

下一个示例演示如何使用 RectangleGeometry 作为图像的剪辑区域。 在此示例中，我们定义了 高度为 200 的 Image 对象。 RectangleGeometry 为要显示的图像区域定义一个矩形。 Rect 属性设置为“25,25,100,150”，它定义从位置“25,25”开始的矩形，宽度为 100，高度为 150。 仅显示矩形区域内的图像部分。

<Image Source="sunset.jpg" Height="200">
    <Image.Clip>
        <RectangleGeometry Rect="25,25,100,150" />
    </Image.Clip>
</Image>

下面是黑色背景上的剪裁图像。

由 RectangleGeometry 裁剪的图像对象。

应用不透明度

可以将不透明度应用于图像，使图像呈现半半透明。 不透明度值从 0.0 到 1.0，其中 1.0 完全不透明，0.0 完全透明。 此示例演示如何将不透明度 0.5 应用于图像。

<Image Height="200" Source="sunset.jpg" Opacity="0.5" />

下面是呈现的图像，其不透明度为 0.5，黑色背景通过部分不透明度显示。

不透明度为 .5 的图像对象。

图像文件格式

图像 和 ImageBrush 可以显示以下图像文件格式：

  • 联合图像专家组 (JPEG)
  • 可移植网络图形 (PNG)
  • 位图 (BMP)
  • 图形交换格式 (GIF)
  • 标记图像文件格式 (TIFF)
  • JPEG XR
  • 图标 （ICO）

Image、BitmapImage 和 BitmapSource 的 API 不包含用于对媒体格式进行编码和解码的任何专用方法。 所有编码和解码操作都是内置的，大多数情况下，编码或解码的方面将作为加载事件事件的事件数据的一部分显示。 如果要对图像编码或解码执行任何特殊工作，如果你的应用正在执行图像转换或操作，则应使用 Windows.Graphics.Imaging 命名空间中可用的 API。 Windows 映像组件（WIC）也支持这些 API。

有关应用资源以及如何在应用中打包图像源的详细信息，请参阅 加载为缩放、主题、高对比度等量身定做的图像和资产。

WriteableBitmap

WriteableBitmap 提供可以修改的 BitmapSource，并且不使用 WIC 中基于文件的基本解码。 可以动态更改图像并重新呈现更新的图像。 若要定义 WriteableBitmap 的缓冲区内容，请使用 PixelBuffer 属性来访问该缓冲区并使用流或语言特定的缓冲区类型来填充它。 有关示例代码，请参阅 WriteableBitmap。

RenderTargetBitmap

RenderTargetBitmap 类可以从正在运行的应用捕获 XAML UI 树，然后表示位图图像源。 捕获后，该图像源可以应用于应用的其他部分、由用户保存为资源或应用数据，或用于其他方案。 一个特别有用的方案是为导航方案创建 XAML 页面的运行时缩略图。 RenderTargetBitmap 对捕获的图像中显示的内容确实存在一些限制。 有关详细信息，请参阅 RenderTargetBitmap 的 API 参考主题。

图像源和缩放

你应该以多个建议的大小创建映像源，以确保你的应用在 Windows 缩放时看起来很棒。 指定图像的源时，可以使用命名约定，该约定会自动引用当前缩放的正确资源。 有关命名约定的详细信息，请参阅 快速入门：使用文件或映像资源。

有关如何设计缩放的详细信息，请参阅 布局和缩放的 UX 指南。

代码中的 Image 和 ImageBrush

通常使用 XAML 而不是代码指定 Image 和 ImageBrush 元素。 这是因为这些元素通常是设计工具作为 XAML UI 定义的一部分的输出。

如果使用代码定义 Image 或 ImageBrush，请使用默认构造函数，然后设置相关的源属性（Image.Source 或 ImageBrush.ImageSource）。 使用代码设置源属性时，源属性需要 BitmapImage （而不是 URI）。 如果源是流，请使用 SetSourceAsync 方法初始化值。 如果源是一个 URI（其中包含应用中使用 ms-appx 或 ms-resource 方案的内容），请使用获取 URI 的 BitmapImage 构造函数。 如果在检索或解码图像资源时存在任何计时问题，而你可能在图像资源可用前需要使用替代内容用以显示，则还可以考虑处理 ImageOpened 事件。 有关示例代码，请参阅 WinUI 库示例。

注意

如果你使用代码建立图像，可以使用自动处理来访问具有当前规模和区域性限定符的非限定资源，或者可以使用具有区域性和规模限定符的 ResourceManager 和 ResourceMap 来直接获取资源。 有关详细信息，请参阅 资源管理系统。

获取示例代码