应用进入发布前自检，经常会给关键页面叠一层“内部校对”水印，让截图流转时能看出素材尚未定稿。问题出在水印叠上去之后：说明文案还看得清，“查看授权说明”按钮却可能不再响应。它看起来像按钮逻辑坏了，实际上可能是一个覆盖在上面的组件吞掉了命中。这里用 ConsentMark 构造一张权限说明预览页，专门分析 ArkUI overlay 的事件边界。本文讨论的是应用内交互自检，不是任何官方审核政策或审核通过经历。## 一、先把页面分成内容层和校对层ConsentMark 不是授权 SDK，也不请求设备权限。它只有三块内容：任务号 CM-052、说明区、一个“查看授权说明”按钮，以及覆盖全页的“内部校对 · CM-052”水印。设计状态为“水印开启 · 按钮可操作”；点按钮后在页面展示“说明面板已打开”，同时记录一个演示状态 PASSED。这些词属于业务测试标记，不能写成“系统权限已经允许”。为什么不用透明度为零的按钮来规避冲突？因为问题不在于水印能不能看见，而在于水印是否参与命中测试。有些方案将水印当成一张半透明全屏图片，直接叠在页面最上层；图片即便只有很低的不透明度，覆盖区域也可能挡住底层按钮。如果为了保留点击，把整个页面设成不响应命中，又会连真正要点的按钮一起损坏。这不是视觉微调能解决的。这类页面的目标应该非常清楚：截图中能看到水印，但水印不承担任何操作；按钮仍然属于内容层。权限说明本身还需要真实可读，水印不能覆盖关键句子。为了让测试可重复，示例把任务号、按钮标题与提示文字固定下来，不引入真实登录态和网络请求。## 二、用 overlay，但不要把它当万能弹窗ArkUI 的 overlay 可以往当前组件上添加文本、CustomBuilder 或 ComponentContent 等浮层内容。华为官方组件参考明确提示：浮层可能覆盖绑定组件下方的交互；当通过 builder 实现不应拦截点击的水印时，可在 builder 最外层组件设置 .hitTestBehavior(HitTestMode.Transparent)。这解决的是命中分发，不是提高透明度。第一个代码片段要解决水印组件自身的命中问题。为了让讨论集中，下面只展示 ConsentPage.ets 中的 builder，渲染仍采用静态文案。水印内容使用任务号，便于与截图和操作记录对应；真正提交应用时，这类内部标记应根据产品审核清单决定是否移除。arkts@Entry@Componentstruct ConsentPage { private readonly taskId: string = 'CM-052'; @State overlayOn: boolean = true; @State hitStatus: string = 'NOT_CHECKED'; @State panelMessage: string = '尚未打开说明'; @Builder watermarkBuilder() { Stack() { Text('内部校对 · CM-052') .fontSize(24) .fontColor('#64748B') .opacity(0.28) } .width('100%').height('100%') .hitTestBehavior(HitTestMode.Transparent) } // build() 与按钮处理逻辑在下文}````HitTestMode.Transparent` 必须落在 builder 最外层的可命中容器上，而不只是作用于内部一行 Text。这一点需要实际项目在目标 API 下验证：组件树上的父级、手势组件以及后来追加的遮罩都可能改变最终命中路径。水印本身不注册 `onClick`，也不存放业务状态。`overlayOn` 控制显示与否，不应该同时用于改变权限授权结果。## 三、把按钮路径写成可观察的最短链路接着解决按钮状态不可追踪的问题。页面不能靠用户说“点了没反应”来定位错误。按钮点击只做三件事：更新状态、填入本地说明文本、写出有限的诊断信息。它不调用不存在的权限接口，也不会打开系统设置页。这里的“说明面板”是 Demo 内的说明块，正式接入时可以替换为产品自己的协议详情页。arktsprivate openExplanation(): void { this.hitStatus = ‘PASSED’; this.panelMessage = ‘说明面板已打开’; console.info([ConsentMark] task=${this.taskId} hit=PASSED); console.info(‘[ConsentMark] dialog=OPEN’);}build() { Column({ space: 16 }) { Text(‘权限说明预览’).fontSize(24).fontWeight(FontWeight.Bold) Text(任务 ${this.taskId}) Text(‘此页用于检查说明文本与交互区域’) Button(‘查看授权说明’).onClick(() => this.openExplanation()) Text(this.panelMessage) Text(命中测试 ${this.hitStatus}) } .padding(20).width(‘100%’) .overlay(this.watermarkBuilder, { align: Alignment.Center })}上述 build 片段展示的是水印开启时的目标形态；如果正式项目允许关闭水印，需要为关闭状态单独提供不含浮层的渲染分支，并保证状态切换不会重新执行授权动作。这里声明了 `overlayOn` 作为演示状态，片段没有展开切换按钮，以免把命中处理和业务授权流程揉在一起。组件 builder 的具体写法及参数形式应以开发工程安装的 SDK API 定义为准，本文没有声称代码已编译通过。在 DevEco 的演示配图中，`hitTestBehavior` 是需要重点检查的一行，右侧界面显示“水印开启”，底部日志显示点击路径。这个展示要强调的是因果链：浮层处理命中，底层按钮执行业务回调，二者不共享触控事件所有权。如果只在按钮回调里加日志却不看浮层，就会误以为没有触发是按钮没有注册事件。![](https://i-blog.csdnimg.cn/direct/26b3fe01e87b4cb8a160009cc2e3c39c.png)## 四、一条测试记录应该覆盖三个不同状态测试口径需要和实际交互拆开。`overlay=ON` 代表水印设计状态；`hit=PASSED` 代表 Demo 的按钮回调已经执行；`dialog=OPEN` 代表本地说明块已显示。这三个标记不是等价的，也不表示审核通过。理想演示日志是 `[ConsentMark] task=CM-052 overlay=ON`、`[ConsentMark] hit=PASSED`、`[ConsentMark] dialog=OPEN`。如果只有第一行，没有后两行，要先检查浮层命中以及按钮是否处于实际可点击区域。为让页面有一个确定的初始状态，可在首次构造演示状态时写出水印标志，而不是每帧打印一次。下面只展示状态归一与轻量记录逻辑，它不涉及系统授权的读取或修改。arktsprivate describePreview(): void { const overlayFlag: string = this.overlayOn ? ‘ON’ : ‘OFF’; console.info([ConsentMark] task=${this.taskId} overlay=${overlayFlag}); if (!this.overlayOn) { this.hitStatus = ‘NOT_CHECKED’; this.panelMessage = ‘尚未打开说明’; }}```这段代码刻意不在 overlayOn 改变时替用户执行点击。状态复位只是让下一轮演示有清晰起点。后续如果把页面改成真实的授权说明入口，需要分别处理页面可见、用户点击、真正的系统授权结果。PASSED 字样只用于本地命中验证，不能放进提交审核资料充当权限同意凭证。点击不通过时，建议按照从外到内的顺序看问题：先确认浮层根节点是否为透明命中，再看其父组件和可能新增的子遮罩，随后检查按钮本身的可点击状态，最后才排查业务回调。若按钮在水印关闭时正常、水印打开时失败，这个对照比盲目加异常捕获更容易缩小范围。若关闭水印仍失败，才应重点调查禁用状态、事件绑定和页面跳转。## 五、这张手机演示图不能替代哪几项验证对应的手机画面用 CM-052 作为唯一任务号，显示“水印开启 · 按钮可操作”“命中测试 PASSED”和“说明面板已打开”。画面中的绿色通过标识只是构造出来的示例结果；图片是设计示意，不是 DevEco 自动抓取的屏幕、无障碍测试报告或系统审批结果。保留这些文字，是为了让开发与评审讨论指向同一个测试用例。真正执行质量验证时，还应在不同字号、横竖屏和窗口宽度下点击按钮的边缘位置，确认水印不会因缩放扩大命中范围；再检查键盘焦点、读屏播报是否能抵达按钮。较长的说明文本需要允许滚动，而不是为了让水印完整显示锁死容器高度。另一个易漏点是弹窗：如果使用实际对话框组件，打开后焦点与返回手势的处理不属于本文这个静态说明块，必须另列检查项。正式上架自检还要查看所有应展示的隐私文案、外链和权限使用说明是否与实际产品一致。本文并未列举审核规则，也不会用一张“点击通过”的截图推断平台审核结论。水印只是内部校对标记，不应在没有评估的情况下进入正式发布包。## 六、最小修复的取舍这个问题最有价值的地方，在于无需改动按钮业务函数就能修正一类交互阻塞：把浮层视为纯展示内容，让它的根节点在命中测试时透明。和挪高按钮层级相比，这种修复更直接表达设计意图，也减少未来更换布局带来的耦合。不过它并不适用于所有遮罩：真正用于禁止操作的模态背景，本来就应该阻挡下层点击，不能盲目改成 Transparent。水印中没有定时器、连接或大型图片缓存，不涉及特殊资源释放；若实际接入远程配置监听、页面弹窗和异步跳转，就应在页面生命周期退出时取消监听、拦截迟到回调。发布前最终交付的是交互可验证性，不是示例图中的“绿色通过”。官方资料参考：华为《浮层》组件参考（2026-08-29 更新），重点核对 overlay、CustomBuilder 与 HitTestMode.Transparent 的说明。本文场景、日志、截图均为可复现实验设计；本次未执行 SDK 编译与真机操作，请在目标项目和实际系统配置下验证。