当前位置：首页 > news >正文

鸿蒙初学者学习手册(HarmonyOSNext_API14)_组件截图（@ohos.arkui.componentSnapshot (组件截图) ）

news 来源：原创 2025/5/29 19:33:59

前言：

这个模块可以截取组件的图片，无论组件是否已加载。截图只能拍到组件本身的大小区域。如果组件或其子组件画得超出了自己的区域，超出的部分不会出现在截图中。截图不会拍到与当前组件平级的（兄弟）组件。

模块简介和注意：

- XComponent场景建议：

如果你正在开发一个视频播放器，应该直接从视频画面获取图片，而不是使用组件的截图功能。

- 组件截图注意事项：

如果有一个按钮，但按钮周围有空白，截图时会显示这些空白为透明。
如果给按钮加了一个阴影效果，截图时可能会看到额外的阴影部分。

简单实例

`componentSnapshot.get`

`get`(`id: string`, `callback: AsyncCallback<image.PixelMap>`, `options?: SnapshotOptions`): `void`

参数	类型	说明
id	string	目标组件标识
callback	AsyncCallback<image.PixelMap>	回调函数
options	SnapshotOptions	截图相关的自定参数

AsyncCallback

AsyncCallback<T, E = void> {(err: BusinessError<E>, data: T): void;}

参数	类型	说明
err	BusinessError	接口调用失败的公共错误信息。
data	T	接口调用时的公共回调信息。

options:SnapshotOptions

参数	类型	说明
scale	number	指定截图时图形侧绘制pixelmap的缩放比。
waitUntilRenderFinished	boolean	指定是否强制等待系统执行截图指令前所有绘制指令都执行完成之后再截图。

先对项目中的关键代码进行简单讲解，最后是

导入模块：

import { componentSnapshot } from '@kit.ArkUI';：导入 componentSnapshot 函数，用于生成组件的快照。
import { image } from '@kit.ImageKit';：导入 image 对象，用于处理图像。

状态变量：

@State pixmap: image.PixelMap | undefined = undefined：定义一个状态变量 pixmap，用于存储图像像素映射，初始值为 undefined。

UI 结构：

Column()：
创建一个垂直排列的容器。
Row()：
创建一个水平排列的容器。
Image(this.pixmap)：
显示一个 Image 组件，使用状态变量 pixmap 作为图像源，设置宽度和高度为 200 像素，添加黑色边框和外边距。
Image($r('app.media.app_icon'))：
显示另一个 Image 组件，使用资源文件 'app.media.app_icon' 作为图像源，自动调整大小，设置宽度和高度为 200 像素，添加外边距，并设置 id 为 "root"。
Button("click to generate UI snapshot")：
创建一个 Button 组件，显示文本 "click to generate UI snapshot"，并设置点击事件处理函数。
onClick(() => { ... })：
设置按钮的点击事件处理函数。
componentSnapshot.get("root", (error: Error, pixmap: image.PixelMap) => { ... }, {scale : 2, waitUntilRenderFinished : true})：使用 componentSnapshot.get 方法生成指定 id 的组件快照。
如果生成快照过程中发生错误，打印错误信息并返回。
如果成功生成快照，将生成的像素映射赋值给状态变量 pixmap。

同步执行

// 导入 @kit.ArkUI 模块中的 componentSnapshot 函数，用于生成组件快照
import { componentSnapshot } from '@kit.ArkUI';
// 导入 @kit.ImageKit 模块中的 image 对象，用于处理图像
import { image } from '@kit.ImageKit';

// 使用 @Entry 装饰器标记该组件为应用的入口组件
@Entry
// 使用 @Component 装饰器标记该类为一个组件
@Component
// 定义名为 SnapshotExample 的结构化组件
struct SnapshotExample {
  // 定义一个状态变量 pixmap，用于存储图像像素映射，初始值为 undefined
  @State pixmap: image.PixelMap | undefined = undefined

  // 定义组件的构建方法，用于描述组件的 UI 结构
  build() {
    // 创建一个垂直排列的容器 Column
    Column() {
      // 创建一个水平排列的容器 Row
      Row() {
        // 显示一个 Image 组件，使用状态变量 pixmap 作为图像源，设置宽度和高度为 200 像素，添加黑色边框和外边距
        Image(this.pixmap)
          .width(200)
          .height(200)
          .border({ color: Color.Black, width: 2 })
          .margin(5)
        // 显示另一个 Image 组件，使用资源文件 'app.media.app_icon' 作为图像源，自动调整大小，设置宽度和高度为 200 像素，添加外边距，并设置 id 为 "root"
        Image($r('app.media.app_icon'))
          .autoResize(true)
          .width(200)
          .height(200)
          .margin(5)
          .id("root")
      }
      // 创建一个 Button 组件，显示文本 "click to generate UI snapshot"，并设置点击事件处理函数
      Button("click to generate UI snapshot")
        .onClick(() => {
          // 使用 componentSnapshot.get 方法生成指定 id 的组件快照
          componentSnapshot.get("root",
            (error: Error, pixmap: image.PixelMap) => {
            // 如果生成快照过程中发生错误，打印错误信息并返回
            if (error) {
              console.log("error: " + JSON.stringify(error))
              return;
            }
            // 如果成功生成快照，将生成的像素映射赋值给状态变量 pixmap
            this.pixmap = pixmap
          }, {scale : 2, waitUntilRenderFinished : true})
        }).margin(10)
    }
    // 设置 Column 容器的宽度为 100%
    .width('100%')
    // 设置 Column 容器的高度为 100%
    .height('100%')
    // 设置 Column 容器的子组件水平对齐方式为居中
    .alignItems(HorizontalAlign.Center)
  }
}

异步执行

import { componentSnapshot } from '@kit.ArkUI';
import { image } from '@kit.ImageKit';

@Entry
@Component
struct SnapshotExample {
  @State pixmap: image.PixelMap | undefined = undefined

  build() {
    Column() {
      Row() {
        Image(this.pixmap).width(200).height(200).border({ color: Color.Black, width: 2 }).margin(5)
        Image($r('app.media.img')).autoResize(true).width(200).height(200).margin(5).id("root")
      }
      Button("click to generate UI snapshot")
        .onClick(() => {
          // 建议使用this.getUIContext().getComponentSnapshot().get()
          componentSnapshot.get("root", {scale : 2, waitUntilRenderFinished : true})
            .then((pixmap: image.PixelMap) => {
              this.pixmap = pixmap
            }).catch((err:Error) => {
            console.log("error: " + err)
          })
        }).margin(10)
    }
    .width('100%')
    .height('100%')
    .alignItems(HorizontalAlign.Center)
  }
}

`componentSnapshot.createFromBuilder`

createFromBuilder(builder: CustomBuilder, callback: AsyncCallback<image.PixelMap>, delay?: number, checkImageStatus?: boolean, options?: SnapshotOptions): void

参数	类型	说明
builder	CustomBuilder	自定义组件构建函数。
callback	AsyncCallback<image.PixelMap>	截图返回结果的回调。
delay	number	指定触发截图指令的延迟时间。默认值：300单位：毫秒
checkImageStatus	boolean	指定是否允许在截图之前，校验图片解码状态。
options	SnapshotOptions	截图相关的自定义参数。