图像和图像画笔

要显示图像，可使用 Image 对象或 ImageBrush 对象。 Image 对象呈现图像，而 ImageBrush 对象使用图像绘制其他对象。

这些是正确的元素吗？

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

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

UWP 和 WinUI 2

重要

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

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

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

• UWP API：Image 类、 Source 属性、 ImageBrush 类、 ImageSource 属性
• 打开 WinUI 2 库应用，查看 ImageBrushes 的运行情况。 WinUI 2 库应用包括大多数 WinUI 2 控件、特性和功能的交互式示例。 通过 Microsoft Store 获取应用，或在 GitHub 上获取源代码。

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

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

注意

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

创建映像

• 重要 API：Image 类、 Source 属性、 ImageBrush 类、 ImageSource 属性

打开 WinUI 3 库应用，查看 ImageBrushes 的运行情况。

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

映像

本示例显示了如何使用 Image 对象创建图像。

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

以下是呈现的 Image 对象。

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

ImageBrush

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

接来下的示例显示如何使用 ImageBrush 绘制 Ellipse。

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

以下是通过 ImageBrush 绘制的 Ellipse。

拉伸图像

如果你没有设置 Image 的 Width 或 Height 值，将以 Source 指定的图像的尺寸显示 。 设置 Width 和 Height 可创建显示图像所在的封闭矩形区域。 你可通过使用 Stretch 属性指定图像填充此封闭区域的方式。 Stretch 属性接受 Stretch 枚举定义的以下值：

• None：该图像未拉伸以适合输出尺寸。 注意此 Stretch 设置：如果源图像大于封闭区域，你的图像将被剪切，但通常不符合预期的，因为你对视口没有任何控制权，就像你处理精修的 Clip 一样。
• Uniform：缩放图像以适应输出尺寸。 但是会保留内容的纵横比。 这是默认值。
• 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>

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

应用不透明度

你可将 Opacity 应用至图像中，以便图像显示为半透明。 不透明度值的范围为 0.0 到 1.0，其中 1.0 为完全不透明，而 0.0 为完全透明。 此示例显示了如何将 0.5 的不透明度应用到图像。

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

以下是呈现的图像，不透明度为 0.5，透过部分不透明的黑色背景。

图像文件格式

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

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

Image、BitmapImage 和 BitmapSource 的 API 不包含任何用于编码和解码媒体格式的专用方法。 所有的编码和解码操作都是内置的，并且至多将编码和解码方面展现为加载事件的事件数据的一部分。 如果你需要对图像编码或解码执行任何特殊工作（你可能会在你的应用执行图像转换或操作时使用该工作），那么你应该使用在 Windows.Graphics.Imaging 命名空间中提供的 API。 这些 API 也受 Windows 中的 Windows 图像处理组件 (WIC) 支持。

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

WriteableBitmap

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

RenderTargetBitmap

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

图像源和缩放

你应该以多个推荐大小创建图像源，以确保你的应用在 Windows 进行缩放时具有良好的外观。 指定 Image 的 Source 时，你可以使用将为当前缩放自动引用正确资源的命名约定。 有关命名约定规范和详细信息，请参阅快速入门：使用文件或图像资源。

有关如何设计缩放的详细信息，请参阅布局和缩放的 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 来直接获取资源。 有关详细信息，请参阅资源管理系统。

获取示例代码

• WinUI 库示例 - 以交互式格式查看所有 XAML 控件。

相关文章

• 音频、视频和相机
• Image 类
• ImageBrush 类