HarmonyOS 7.0 / API 26 安全截图防护排查：敏感页录屏、截图和多窗口预览如何分开处理
先把问题摆出来
这篇只讲一个点：安全截图防护。我不按官方说明书那种顺序铺概念，而是按开发时最容易出事的路径来拆：什么时候会坏、怎么复现、怎么修、怎么验证，以及这个判断以后能不能复用。
敏感页最怕只挡住截图，却漏掉多窗口预览、最近任务缩略图或者录屏路径。开发时必须把入口、窗口状态和回退提示一起设计。
本文按 HarmonyOS 7.0 / API 26 的能力边界来写。重点不是堆 API 名称，而是把版本、设备状态、窗口形态、异常回退和日志证据放到同一套检查里，避免上线后靠猜。
版本边界和适用场景
| 检查项 | 处理口径 |
|---|---|
| 系统版本 | HarmonyOS 7.0，API 26 |
| 适用方向 | 安全与上架审核、窗口状态、敏感信息保护 |
| 开发者会搜的问题 | 敏感页面为什么截图挡住了但任务预览还会暴露 |
| 不建议的写法 | 只在按钮点击时做一次截图拦截 |
| 推荐的收口方式 | 按窗口状态统一判断截图、录屏和预览策略 |
我建议先把版本边界写进代码，而不是先写 UI。原因很简单：UI 层最容易变，能力边界最应该稳定。入口层先判断清楚，后面的页面、组件、服务只接收明确结果，排查时日志也更集中。
案例一：先复现一个会错的写法
下面这个例子故意保留了常见问题：入口直接执行，异步结果没有版本号保护，窗口变化或用户重复触发时，旧结果可能覆盖新结果。
typeGuardInput={apiLevel:numberdeviceReady:booleanwindowStable:booleanpayload:string}typeGuardResult={ok:booleanmode:'full'|'fallback'|'blocked'reason:string}classUnsafeRunner{asyncrun(input:GuardInput):Promise<GuardResult>{awaitnewPromise<void>((resolve)=>setTimeout(resolve,160))if(input.apiLevel<26){return{ok:false,mode:'fallback',reason:'api level below 26'}}if(!input.deviceReady){return{ok:false,mode:'blocked',reason:'device is not ready'}}return{ok:true,mode:'full',reason:'accepted'}}}这个版本的问题是，它只在执行时判断一次。页面如果发生分屏、拖拽、横竖屏切换、蓝牙设备变化、低电量降级或者用户连续触发，旧任务仍然可能回来写状态。开发环境里可能看不出来，到了真机和复杂窗口里就会变成偶发问题。
案例二：把入口判断和结果保护补上
更稳的写法是：每次触发都生成一个请求版本号；返回结果时先判断自己是不是最新任务；再根据 API 级别、设备能力和窗口稳定性决定走完整能力还是回退路径。
classFeatureGuard{privatelatestVersion=0asyncrun(input:GuardInput):Promise<GuardResult>{constversion=++this.latestVersionconstprepared=this.prepare(input)if(prepared.mode!=='full'){returnprepared}awaitnewPromise<void>((resolve)=>setTimeout(resolve,160))if(version!==this.latestVersion){return{ok:false,mode:'blocked',reason:'stale result ignored'}}return{ok:true,mode:'full',reason:'finished by current request'}}privateprepare(input:GuardInput):GuardResult{if(input.apiLevel<26){return{ok:false,mode:'fallback',reason:'HarmonyOS API level below 26'}}if(!input.deviceReady){return{ok:false,mode:'blocked',reason:'capability is not ready'}}if(!input.windowStable){return{ok:false,mode:'fallback',reason:'window state is changing'}}if(!input.payload.trim()){return{ok:false,mode:'blocked',reason:'payload is empty'}}return{ok:true,mode:'full',reason:'guard passed'}}}这段代码的价值不在于复杂，而在于把问题收口了：入口负责判断，执行负责完成，返回负责防旧结果。以后换成 安全截图防护 的真实能力调用时，也可以沿用同一套结构。
两种方案对比
| 方案 | 优点 | 风险 |
|---|---|---|
| 页面里直接调用能力 | 写起来最快 | 版本、窗口、设备能力分散在页面里，出问题难查 |
| 每个组件自己兜底 | 局部改动小 | 判断重复，日志不统一，后期维护成本高 |
| 统一 guard 后再执行 | 日志集中，可复用，可测试 | 前期要多写一层适配代码 |
我会选第三种。HarmonyOS 7.0 / API 26 的新能力越来越多，真正影响项目稳定性的不是“能不能调一次”，而是各种状态变化下能不能知道自己为什么走完整能力、为什么回退、为什么拒绝执行。
验证方式
验证不要只看页面有没有打开。建议至少压下面五个点：
- API level 低于 26 时，必须走 fallback，不允许继续完整能力路径。
- deviceReady 为 false 时，必须给出 blocked 和明确 reason。
- windowStable 为 false 时，必须走 fallback，避免拖拽或分屏中反复刷新。
- 连续触发两次时，旧请求返回不能覆盖新请求。
- 日志里必须能看到 mode、reason、requestId，便于回查。
可以加一个很轻的日志封装：
functionbuildFeatureLog(name:string,input:GuardInput,result:GuardResult):string{return['feature='+name,'api='+input.apiLevel,'mode='+result.mode,'reason='+result.reason,].join(' | ')}期望日志类似这样：
feature=api26-secure-screenshot | api=26 | mode=fallback | reason=window state is changing可以怎么封装复用
如果项目里多个页面都要接入类似能力，可以把判断做成一个小模块：
exportclassApi26FeatureAdapter{constructor(privatereadonlyfeatureName:string){}check(input:GuardInput):GuardResult{if(input.apiLevel<26){return{ok:false,mode:'fallback',reason:this.featureName+': api level below 26'}}if(!input.deviceReady||!input.windowStable){return{ok:false,mode:'fallback',reason:this.featureName+': runtime state is not stable'}}return{ok:true,mode:'full',reason:this.featureName+': ready'}}}页面只负责把当前状态传进来。这样后面要适配折叠屏、平板、鸿蒙电脑、多窗口或者低电量策略时，不需要把每个页面都翻一遍。
最后给一个检查清单
- 先确认 HarmonyOS 7.0 / API 26 的版本边界，再写调用。
- 至少准备两个场景：正常路径和回退路径。
- 每个回退都要有 reason，不能只返回 false。
- 异步结果要防旧请求覆盖新请求。
- 多窗口、弱网、低电量、设备能力不足，至少挑两个压测。
- 上架前把截图、权限说明、失败提示和降级表现一起检查。
如果你也遇到 安全截图防护 相关问题，可以从日志里的 mode 和 reason 开始排，一般比直接翻 UI 代码快很多。