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

前言：

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

模块简介和注意：

- 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	截图相关的自定义参数。

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。

同步执行

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

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

  // 定义一个构建器方法 RandomBuilder，用于生成随机内容的 UI 结构
  @Builder
  RandomBuilder() {
    // 创建一个垂直排列的 Flex 容器，设置主轴对齐方式为居中，交叉轴对齐方式为居中
    Flex({ direction: FlexDirection.Column, justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) {
      // 显示一个 Text 组件，显示文本 'Test menu item 1'，设置字体大小为 20 像素，宽度为 100 像素，高度为 50 像素，文本对齐方式为居中
      Text('Test menu item 1')
        .fontSize(20)
        .width(100)
        .height(50)
        .textAlign(TextAlign.Center)
      // 显示一个 Divider 组件，设置高度为 10 像素
      Divider().height(10)
      // 显示另一个 Text 组件，显示文本 'Test menu item 2'，设置字体大小为 20 像素，宽度为 100 像素，高度为 50 像素，文本对齐方式为居中
      Text('Test menu item 2')
        .fontSize(20)
        .width(100)
        .height(50)
        .textAlign(TextAlign.Center)
    }
    // 设置 Flex 容器的宽度为 100 像素，并设置 id 为 "builder"
    .width(100)
    .id("builder")
  }

  // 定义组件的构建方法，用于描述组件的 UI 结构
  build() {
    // 创建一个垂直排列的 Column 容器
    Column() {
      // 创建一个 Button 组件，显示文本 "click to generate offscreen UI snapshot"，并设置点击事件处理函数
      Button("click to generate offscreen UI snapshot")
        .onClick(() => {
          // 使用 componentSnapshot.createFromBuilder 方法生成指定构建器的快照
          componentSnapshot.createFromBuilder(
            () => { this.RandomBuilder() }, // 提供构建器方法
            (error: Error, pixmap: image.PixelMap) => { // 回调函数处理生成的快照或错误
              // 如果生成快照过程中发生错误，打印错误信息并返回
              if (error) {
                console.log("error: " + JSON.stringify(error))
                return;
              }
              // 如果成功生成快照，将生成的像素映射赋值给状态变量 pixmap
              this.pixmap = pixmap
              // 保存 pixmap 到文件（此处注释掉）
              // ....
              // 获取组件的尺寸和位置信息
              let info = this.getUIContext().getComponentUtils().getRectangleById("builder")
              // 打印组件的宽度、高度以及不同坐标系下的位置信息
              console.log(info.size.width + ' ' + info.size.height + ' ' + info.localOffset.x + ' ' + info.localOffset.y + ' ' + info.windowOffset.x + ' ' + info.windowOffset.y)
            },
            320, // 设置生成快照的宽度为 320 像素
            true, // 设置是否使用硬件加速
            { scale: 2, waitUntilRenderFinished: true } // 设置缩放比例为 2，等待渲染完成后再生成快照
          )
        })
      // 显示一个 Image 组件，使用状态变量 pixmap 作为图像源，设置外边距为 10 像素，高度为 200 像素，宽度为 200 像素，添加黑色边框
      Image(this.pixmap)
        .margin(10)
        .height(200)
        .width(200)
        .border({ color: Color.Black, width: 2 })
    }
    // 设置 Column 容器的宽度为 100%，设置外边距为左 10 像素，上 5 像素，下 5 像素，设置高度为 300 像素
    .width('100%')
    .margin({ left: 10, top: 5, bottom: 5 })
    .height(300)
  }
}