想做"一键生成分享海报":用户的日记内容 + 装饰元素渲染成 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 既不占位又正常 rendercomponentSnapshot.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 代码。