一张图搞懂 HarmonyOS SnapshotUtil：什么场景用哪个截图方法？

背景

近期发现一款很有意思的HarmonyOS 三方库, 地址 @pura/harmony-utils(V1.4.0) , 作者是"桃花镇童长老", 我这里也是直接通过该作者公布的源码进行案例编写进行,写了到目前写了一部分demo ,感觉确实很有帮助,这里呢也是开始写一个系列的演示demo 供大家参考。如有帮助可以在OpenHarmony中进行下载安装进行使用哦

案例demo导航展示

↓↓↓↓↓↓接下来言归正传 ↓↓↓↓

截图功能在移动应用里非常普遍：分享内容、生成海报、截屏检测……前面分三篇分别讲了SnapshotUtil的各个方法。这篇做个总结，把四种截图方式放在一起，告诉你什么场景用哪个。

方法总览

四种截图方式一览

场景一：截取页面上某个区域

比如截取商品卡片、文章预览、用户信息卡：

给目标组件设置 id：

Column({space:8}){Text('这是一个演示组件').fontSize(16).fontColor('#333').fontWeight(FontWeight.Bold)Text('可对该区域进行组件截图').fontSize(13).fontColor('#666')Row({space:8}){ForEach(['红','绿','蓝'],(label:string,idx:number)=>{Column(){Circle({width:40,height:40}).fill(idx===0?'#FF6B6B':idx===1?'#4ECDC4':'#45B7D1')Text(label).fontSize(12).fontColor('#666')}},(label:string)=>label)}}.id('snapshot_target')// 必须设置 id.width('100%').padding(16).backgroundColor('#FFFFFF').borderRadius(10).border({width:2,color:'#4A90E2',style:BorderStyle.Dashed})

调用截图：

// 基础截图SnapshotUtil.get('snapshot_target').then(pm=>{this.snapshotPixelMap=pm;this.addLog(`get("snapshot_target") → PixelMap${pm.getPixelBytesNumber()}bytes`);}).catch((e:Error)=>{this.addLog(`get() Error:${e.message}`);});// 缩放截图（减少文件大小）SnapshotUtil.get('snapshot_target',{scale:0.5}).then(pm=>{this.snapshotPixelMap=pm;this.addLog(`get("snapshot_target", {scale:0.5}) →${pm.getPixelBytesNumber()}bytes`);}).catch((e:Error)=>{this.addLog(`get() Error:${e.message}`);});

场景二：生成分享卡片（不需要显示在屏幕上）

生成海报、分享图，内容不需要让用户看到：

定义离屏 Builder（必须在 struct 外部）：

@BuilderfunctionbuilderParam(){Column({space:6}){Text('SnapshotUtil 离屏渲染示例').fontSize(16).fontColor('#FFFFFF').fontWeight(FontWeight.Bold)Text('createFromBuilder 截图内容').fontSize(12).fontColor('#CCFFCC')Row({space:6}){Circle({width:20,height:20}).fill('#FF6B6B')Circle({width:20,height:20}).fill('#4ECDC4')Circle({width:20,height:20}).fill('#FFE66D')}}.width(260).height(100).backgroundColor('#2C3E50').borderRadius(12).justifyContent(FlexAlign.Center).alignItems(HorizontalAlign.Center)}

生成截图：

// 基础版（delay 300ms，不检查图片状态）SnapshotUtil.createFromBuilder(builderParam,300,false).then(pm=>{this.builderPixelMap=pm;this.addLog(`createFromBuilder() → PixelMap${pm.getPixelBytesNumber()}bytes`);}).catch((e:Error)=>{this.addLog(`createFromBuilder() Error:${e.message}`);});// 有网络图片时，delay 长一点并检查图片状态SnapshotUtil.createFromBuilder(builderParam,500,true).then(pm=>{this.builderPixelMap=pm;this.addLog(`createFromBuilder(delay=500) →${pm.getPixelBytesNumber()}bytes`);}).catch((e:Error)=>{this.addLog(`createFromBuilder Error:${e.message}`);});

场景三：截取整个应用窗口

SnapshotUtil.snapshot().then(pm=>{this.addLog(`snapshot() → PixelMap${pm.getPixelBytesNumber()}bytes`);}).catch((e:Error)=>{this.addLog(`snapshot() Error:${e.message}`);});

适合"截图反馈 Bug"功能——用户报问题时，自动截取当前页面截图附上。

场景四：截屏行为监听

监听用户的系统截图操作：

@StateisListening:boolean=false;privatesnapshotListener:VoidCallback=()=>{this.addLog('[系统截图事件] 检测到截屏操作！');};// 开关监听if(this.isListening){SnapshotUtil.removeSnapshotListener(this.snapshotListener);this.isListening=false;this.addLog('removeSnapshotListener(callback) 已关闭截图监听');}else{SnapshotUtil.onSnapshotListener(this.snapshotListener);this.isListening=true;this.addLog('onSnapshotListener() 已开启截图监听，请按下截图键触发...');}

适合聊天应用、隐私内容页面的截图提醒功能。

选型决策树

有截图需求 ├── 需要截取屏幕上已有组件？ │ ├── 是 → 给组件加 id │ │ ├── 需要立即拿到结果 → getSync(id) │ │ └── 普通场景 → get(id) │ └── 否 │ ├── 需要动态生成图片（海报、卡片）→ createFromBuilder │ └── 需要截取整个窗口 → snapshot() │ └── 需要监听用户截屏行为？→ onSnapshotListener / removeSnapshotListener

PixelMap 得到后能做什么？

无论用哪种方式拿到PixelMap，后续操作都一样：

// 1. 直接显示Image(this.snapshotPixelMap).width('100%').height(120).objectFit(ImageFit.Contain).backgroundColor('#F0F0F0').borderRadius(8)// 2. 保存为文件（配合 ImageUtil 或 image.ImagePacker）// 3. 分享（传给系统分享面板）// 4. 上传到服务器（先打包成 JPEG/PNG 字节流）

写在最后

SnapshotUtil四个截图功能覆盖了移动应用里绝大多数截图需求。关键是搞清楚：你要截的内容是"已经在屏幕上的"还是"需要动态生成的"，然后选对方法。