HarmonyOS SnapshotUtil 窗口截图与系统截屏监听：snapshot() 和 onSnapshotListener 详解

背景

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

案例demo导航展示

↓↓↓↓↓↓接下来言归正传 ↓↓↓↓
前两篇讲了组件级截图（get()和createFromBuilder），这篇来讲两个更"高级"的功能：

1. snapshot()：截取整个应用窗口
2. onSnapshotListener()：监听用户的系统截屏操作（用户按下截图键时你能收到通知）

方法总览

snapshot()：截取主窗口

snapshot()不需要指定组件 id，它直接截取整个应用窗口的内容，返回PixelMap。

this.Btn('snapshot() 截取主窗口','#E74C3C',()=>{SnapshotUtil.snapshot().then(pm=>{this.addLog(`snapshot() → PixelMap${pm.getPixelBytesNumber()}bytes`);}).catch((e:Error)=>{this.addLog(`snapshot() Error:${e.message}`);});})

用法和get()类似，也是返回 Promise，在.then()里拿到PixelMap。

注意：snapshot()截取的是应用窗口内容，系统状态栏、导航栏通常不在截图范围内，具体取决于系统版本和窗口配置。

onSnapshotListener：监听系统截屏事件

这个功能比较特别——它不是让你主动截图，而是监听用户使用系统截图功能（按音量键+电源键，或者三指滑动）的行为。

应用场景：

• 聊天应用提示"对方对本页面进行了截图"
• 敏感内容页面的截图提醒
• 截图后自动弹出分享对话框

开启监听：

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

注意snapshotListener定义在组件的成员变量里，是一个VoidCallback类型的函数。必须保存这个函数引用，后面取消监听时需要用到同一个引用。

关闭特定监听：

// 取消指定的监听（传入之前保存的 listener 引用）SnapshotUtil.removeSnapshotListener(this.snapshotListener);this.isListening=false;this.addLog('removeSnapshotListener(callback) 已关闭截图监听');

关闭所有监听：

// 不传参数，关闭所有截屏监听SnapshotUtil.removeSnapshotListener();this.isListening=false;this.addLog('removeSnapshotListener() 已关闭所有截图监听');

完整监听开关实现

@StateisListening:boolean=false;privatesnapshotListener:VoidCallback=()=>{this.addLog('[系统截图事件] 检测到截屏操作！');};// UI 部分Row({space:8}){Button(this.isListening?'关闭监听':'开启监听').layoutWeight(1).height(40).fontSize(14).fontColor('#fff').backgroundColor(this.isListening?'#E74C3C':'#27AE60').borderRadius(8).onClick(()=>{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() 已开启截图监听，请按下截图键触发...');}})Button('removeSnapshotListener() 关闭所有').layoutWeight(1).height(40).fontSize(13).fontColor('#fff').backgroundColor('#F39C12').borderRadius(8).onClick(()=>{SnapshotUtil.removeSnapshotListener();this.isListening=false;this.addLog('removeSnapshotListener() 已关闭所有截图监听');})}// 状态指示器Row({space:8}){Circle({width:10,height:10}).fill(this.isListening?'#2ECC71':'#BDC3C7')Text(this.isListening?'截图监听中...':'截图监听未开启').fontSize(13).fontColor(this.isListening?'#27AE60':'#999')}

这个实现有个小细节值得学：用@State isListening: boolean来控制按钮文字和颜色，监听开启时按钮变红色显示"关闭监听"，没开启时显示绿色"开启监听"。这种"状态驱动 UI"的写法是 ArkTS 的标准范式。

使用注意事项

1. Listener 引用要保存

onSnapshotListener注册的 listener 和removeSnapshotListener取消时，必须是同一个函数引用。如果每次都传匿名函数，就没法精确取消：

// ❌ 错误：每次 onClick 都创建新的匿名函数，removeSnapshotListener 找不到原来那个SnapshotUtil.onSnapshotListener(()=>{console.log('截图了');});// 之后这样取消是无效的，因为引用不同SnapshotUtil.removeSnapshotListener(()=>{console.log('截图了');});// ✅ 正确：保存引用privatemyListener:VoidCallback=()=>{console.log('截图了');};SnapshotUtil.onSnapshotListener(this.myListener);// 取消时用同一个引用SnapshotUtil.removeSnapshotListener(this.myListener);

2. 记得在页面销毁时取消监听

如果你在页面里开启了截屏监听，记得在aboutToDisappear()生命周期里取消：

aboutToDisappear(){SnapshotUtil.removeSnapshotListener(this.snapshotListener);}

不取消的话，页面销毁了 listener 还在，可能导致内存泄漏或回调到已销毁的组件。

SnapshotUtil 功能总结

写在最后

截屏监听这个功能在国内社交应用里特别常见——聊天消息截图提醒几乎是标配。onSnapshotListener让你在 HarmonyOS 上实现这个功能变得很简单，几行代码搞定。

记住要保存 listener 引用，记住页面销毁时取消监听，就没什么坑了。