HarmonyOS 鸿蒙Next开发 / ArkTS / 组件截图 / PixelMap / 长截图拼接 / UI截图

HarmonyOS 鸿蒙Next开发 / ArkTS / 组件截图 / PixelMap / 长截图拼接 / UI截图 在鸿蒙开发中，经常会遇到这样一个需求：

把多个不在同一个容器里的组件截图，按顺序拼接成一张长图。

官方示例大多是「滚动列表长截图」，但多组件静态拼接几乎没有完整范例。

下面分享一个可直接复用的多组件拼接截图方案，核心思路专注在 PixelMap 的读取与合成。

一、整体思路说明

1. 逐个组件截图
   • 使用 getComponentSnapshot().getSync
   • 拿到每个组件对应的 PixelMap
2. 读取像素数据
   • 通过 readPixelsToBufferSync 将像素读入 ArrayBuffer
   • 封装为 image.PositionArea
3. 统一创建目标 PixelMap
   • 高度 = 所有组件高度之和
   • 宽度 = 所有组件的最大宽度
4. 按顺序写入像素
   • 使用 writePixelsSync
   • 通过 y 偏移量逐段往下写，实现“拼接”

整个过程不做 canvas 绘制、不做 bitmap 转换，完全是底层像素级拼接，性能和清晰度都很稳。

二、核心代码实现

export class SnapshotManager {

  /**
   * 拼接多个指定 ID 的组件为一张长图
   * @param uiContext UIContext
   * @param ids 组件 ID 数组（顺序即拼接顺序）
   */
  static concatComponentSnapshots(
    uiContext: UIContext,
    ids: string[]
  ): image.PixelMap {
    let areaArray: image.PositionArea[] = []
    let totalHeight = 0
    let maxWidth = 0
    // 1. 逐个组件截图并读取像素
    for (const id of ids) {
      const pm = uiContext
        .getComponentSnapshot()
        .getSync(id, { waitUntilRenderFinished: true })
      const info = pm.getImageInfoSync()
      const bytes = pm.getPixelBytesNumber()
      const buffer = new ArrayBuffer(bytes)
      // 读取像素
      pm.readPixelsToBufferSync(buffer)
      // 封装为 PositionArea
      const area: image.PositionArea = {
        pixels: buffer,
        offset: 0,
        stride: info.size.width * 4,
        region: {
          x: 0,
          y: 0,
          size: {
            width: info.size.width,
            height: info.size.height
          }
        }
      }
      areaArray.push(area)
      totalHeight += info.size.height
      maxWidth = Math.max(maxWidth, info.size.width)
      // 释放资源
      pm.release()
    }
    // 2. 创建目标长图 PixelMap
    const longPixelMap = image.createPixelMapSync({
      editable: true,
      pixelFormat: 4, // RGBA_8888
      size: {
        width: maxWidth,
        height: totalHeight
      }
    })
    // 3. 按顺序写入像素数据
    let currentY = 0
    for (const area of areaArray) {
      const writeArea: image.PositionArea = {
        pixels: area.pixels,
        offset: 0,
        stride: area.stride,
        region: {
          x: 0,
          y: currentY,
          size: area.region.size
        }
      }
      longPixelMap.writePixelsSync(writeArea)
      currentY += area.region.size.height
    }
    return longPixelMap
  }
}

三、最后

需要传入截图组件的必要ID即可获得长截图后的PixelMap