HarmonyOS ArkUI 用 position(x:-9999) 做离屏节点生成高分辨率分享海报

1 阅读7分钟

想做"一键生成分享海报":用户的日记内容 + 装饰元素渲染成 1080×1080 的 PNG,直接存相册或分享。朴素思路是用户点击后弹一个 1080×1080 的面板,截图保存——但手机屏幕宽度只有 400 多 vp,1080 的组件直接显示会超屏。换个思路:把海报组件挂在屏幕外(position x=-9999),用户看不到,但 ArkUI 照常渲染,componentSnapshot.get(id) 能拿到完整的 1080×1080 像素图。做某个极简日记 app 时用了这招,效果意外的好。记录一下,顺便分享给有需要的朋友。

一、朴素做法为什么不行

直接把高分辨率的组件放到屏幕上:

build() {
  Column() {
    // 页面主体 UI
    Column() { /* ... */ }
      .width('100%')
      .height('80%')

    // 海报组件
    if (this.showPoster) {
      PosterCanvas({
        content: this.content,
      })
        .width(1080)
        .height(1080)
    }
  }
}

问题:

  • 手机屏幕宽 ~400 vp(P60 大约 393vp,Mate 60 大约 400vp)。1080vp 的组件超出屏幕,用户看到的是左上角一部分
  • ArkUI 的 clip 机制可能把超出部分真的 clip 掉——componentSnapshot.get(id) 拿到的也是 clip 后的局部,不是完整 1080×1080
  • 弹出来再隐藏的过渡期用户看到闪一下奇怪 UI,体验差

二、position({ x: -9999 }) 的 trick

真实代码:

// WritePage.ets:149
build() {
  Stack() {
    // 页面主体 UI
    Column() {
      // ... 日记编辑界面
    }

    // 👇 离屏海报节点
    PosterCanvas({
      content: this.content,
      date: this.today,
      // ...
    })
      .width(1080)
      .height(1080)
      .id('posterCanvas')
      .position({ x: -9999 })     // ← 关键
  }
}

原理:

.position({ x: -9999 }) 把组件挪到屏幕外的左边 9999vp。手机屏幕坐标 0 到 ~400,-9999 远远在屏幕外。用户完全看不到。

但 ArkUI 照常渲染。只要组件在 UI 树里,它就被 render 系统正常处理——测量、布局、绘制全走一遍。1080×1080 的像素阵列真实存在于显存中,只是显示位置在屏幕外。

componentSnapshot.get(id) 能拿到完整像素。rendering 的结果是真实的,snapshot API 读的是 render tree 的 PixelMap,不受屏幕位置影响。

// PosterService.ets:9
async generatePoster(context: Context, componentId: string): Promise<string> {
  const pixelMap: image.PixelMap = await componentSnapshot.get(componentId)
  // pixelMap 是完整的 1080×1080,不是屏幕显示的那部分
  // ... pack 成 PNG 保存
}

三、为什么 x=-9999 不是 opacity=0 或 visibility=hidden

有几个候选方案都看起来能"隐藏但保留 render":

Option A: .opacity(0) 透明

PosterCanvas()
  .width(1080)
  .height(1080)
  .opacity(0)

❌ 不行:opacity 0 的组件在屏幕内,依然占据布局空间。1080×1080 的占位会把其他组件挤飞。

Option B: .visibility(Visibility.Hidden) 隐藏但占位

PosterCanvas()
  .visibility(Visibility.Hidden)

❌ 不行:Hidden 占位相当于 opacity 0。

Option C: .visibility(Visibility.None) 完全不渲染

PosterCanvas()
  .visibility(Visibility.None)

❌ 不行:None 不占位但也跳过 render,componentSnapshot 拿不到。

Option D: .position({ x: -9999 }) 挪屏幕外

PosterCanvas()
  .width(1080)
  .height(1080)
  .position({ x: -9999 })

✅ 行:position 是绝对定位,组件脱离正常布局流。不占位、不挤其他组件。但 render tree 里正常存在,snapshot 能拿到。

为什么 position 能做到:.position(...) 等价于 CSS 的 position: absolute,组件被从布局流里拿掉(不占空间),但 render tree 里独立存在。-9999 的 x 让它绘制到屏幕外,视觉上消失。

四、PosterService 的完整流程

把 pixelMap 保存成 PNG 文件:

// PosterService.ets:9
async generatePoster(
  context: common.UIAbilityContext,
  componentId: string,
): Promise<string> {
  try {
    // 1. 截图(离屏节点的完整像素)
    const pixelMap: image.PixelMap = await componentSnapshot.get(componentId)

    // 2. 创建 ImagePacker + 配 PNG 选项
    const imagePackerApi = image.createImagePacker()
    const packOpts: image.PackingOption = {
      format: 'image/png',
      quality: 95,
    }

    // 3. packing 返回 ArrayBuffer
    const arrayBuffer = await imagePackerApi.packing(pixelMap, packOpts)

    // 4. 写入临时文件
    const timestamp = Date.now()
    const filePath = `${context.tempDir}/sixechoes_poster_${timestamp}.png`
    const file = fileIo.openSync(
      filePath,
      fileIo.OpenMode.CREATE | fileIo.OpenMode.WRITE_ONLY | fileIo.OpenMode.TRUNC,
    )
    fileIo.writeSync(file.fd, arrayBuffer)
    fileIo.closeSync(file.fd)

    // 5. 释放资源
    imagePackerApi.release()
    pixelMap.release()

    return filePath
  } catch (e) {
    throw new Error(`Poster generation failed: ${e}`)
  }
}

async savePosterToFiles(
  context: common.UIAbilityContext,
  filePath: string,
): Promise<boolean> {
  try {
    const destDir = context.filesDir
    const destPath = `${destDir}/sixechoes_poster_latest.png`
    fileIo.copyFileSync(filePath, destPath)
    return true
  } catch (e) {
    return false
  }
}

几个点:

packing 返回 ArrayBuffer 不是 fd。相比之下 packToFile 接 fd 直接写文件,这里用 packing 拿到 ArrayBuffer 再手动 fileIo.writeSync(fd, buffer)。两种 API 都行,packing 的好处是中间 buffer 可以进一步处理(比如用 CryptoFramework 加密再写)。

tempDir vs filesDir:

  • context.tempDir → 临时目录,系统可能清理。适合"刚生成马上要用"的中间文件
  • context.filesDir → 持久目录,app 卸载时清理。适合"要保留"的文件

PosterService 先把海报写到 tempDir(分享面板读完就可以不用了),savePosterToFiles 再 copy 到 filesDir 作为"最新海报"的持久备份。

quality: 95 对 PNG 无效。PNG 是无损格式,quality 参数被忽略。但传 95 不会报错。

资源释放顺序:imagePacker → pixelMap。两个都要 release,不然内存涨。

五、PosterCanvas 组件的高分辨率设计

海报组件本身要能适应 1080×1080 的画布:

@Component
export struct PosterCanvas {
  @Prop content: string
  @Prop date: string
  @Prop decoration: string

  build() {
    Column() {
      // 顶部装饰
      Column() {
        Text(this.date)
          .fontSize(48)                   // 字号大
          .fontWeight(FontWeight.Bold)
      }
      .height(200)

      // 中间内容区
      Text(this.content)
        .fontSize(72)                     // 主内容更大
        .padding(80)
        .textAlign(TextAlign.Center)

      // 底部装饰
      Row() {
        Text('六迹').fontSize(32)
        Text('·').fontSize(32).padding({ left: 8, right: 8 })
        Text(this.date).fontSize(32)
      }
      .height(120)
    }
    .width(1080)
    .height(1080)
    .backgroundColor('#F8F6F1')
  }
}

字号用 vp 为单位,1080×1080 的画布上 48vp 字号大概是 ~48 像素高(看 dpr)。相对于 400vp 屏幕上 48vp 字体很小,但在 1080×1080 的海报上比例合适。

padding 也要按比例。手机屏幕上 padding 16 已经不少,但 1080 画布上 padding 80 才看起来舒服。

不要用 fx 单位 / 百分比:有些开发者用 '5%',1080×1080 画布上的 5% 和手机屏的 5% 是不同的物理值。vp 固定值更可控。

六、什么时候触发生成

点击 "生成海报" 按钮时:

async onGeneratePoster(): Promise<void> {
  try {
    const context = getContext(this) as common.UIAbilityContext
    // 等一帧,确保离屏节点的最新 state 渲染到 render tree
    await new Promise<void>(resolve => setTimeout(resolve, 50))

    // 生成海报
    const filePath = await this.posterService.generatePoster(context, 'posterCanvas')
    const saved = await this.posterService.savePosterToFiles(context, filePath)

    // 分享或保存相册的后续流程
    if (saved) {
      this.invokeSharePanel(context, 'file://' + filePath)
    }
  } catch (e) {
    this.showToast('生成失败')
  }
}

等一帧的 50ms:如果你刚修改了 content state,然后立刻 componentSnapshot.get,可能拿到的是旧 render(新 state 还没应用到 render tree)。setTimeout(50) 让一次 ArkUI 的 vsync 过去,state 应用完再截图。

对生成分享海报这种一次性操作 50ms 延迟用户感知不到。但做 60fps 实时截图肯定不能这样。

七、x = -9999 够不够远

有人问:手机屏幕宽度 400vp,position({ x: -500 }) 够不够?

理论上够(-500 已经在屏幕外)。但:

  • 折叠屏展开态屏幕宽度 ~800vp,-500 可能露一点
  • 平板横屏 1200+ vp,-500 直接可见
  • 跨设备保险起见 x = -9999 远远在任何屏幕外

另一个方向:y = -9999 挪到屏幕上方也行。但 向左挪比向上挪更稳——因为滚动容器的默认滚动方向是垂直,向上挪的组件可能被父容器的 overflow 异常处理触发额外成本。

踩坑清单

  • 高分辨率海报的离屏节点用 .position({ x: -9999 }) 挪到屏幕外
  • opacity: 0 / visibility: Hidden 还占位;visibility: None 不 render,snapshot 拿不到;只有 position 既不占位又正常 render
  • componentSnapshot.get(id) 读的是 render tree 的 PixelMap,不受屏幕位置影响
  • imagePacker.packing(pixelMap, opts) 返回 ArrayBuffer → 手动 fileIo.writeSync 到文件
  • 临时文件写 tempDir,持久备份 copy 到 filesDir
  • Haikucard 组件内部字号/padding 要按 1080 画布比例(48vp / 80vp 这种大数值)
  • 截图前 setTimeout(50) 等一帧,确保最新 state 应用到 render tree
  • x = -9999 保证跨设备(手机 / 折叠屏 / 平板)都在屏幕外

尾声

这招"离屏画布"在 Web 时代就有——Canvas 创建一个 1920×1080 的 canvas 不挂到 DOM,drawImage + toDataURL 导出。鸿蒙的做法是组件挪屏幕外,本质一样。

独立开发者尤其喜欢这招。做 app 时经常有"比屏幕大的内容要导出"的需求:

  • 长截图(整页截图)→ ScrollContainer 挪屏幕外
  • 分享卡片 → 固定尺寸组件挪屏幕外
  • 带 QR 码的凭证 → 高清组件挪屏幕外
  • Instagram 风格的"动态"卡片 → 1080×1920 组件挪屏幕外

都是同一个 pattern。知道这个 trick 省了一堆 Canvas 代码。