HarmonyOS 7 智慧手势不响应先查 enabled、selectable再查监听器有没有截走动作给按钮加了智慧手势属性画面没有选中框就认定接口没生效于是又注册一个监听器结果另一个页面的监听也收不到动作。这两种现象看起来都是“手势失灵”查的却不是同一层前者要区分响应开关和视觉反馈后者要看监听顺序与消费结果。下面用一个计数按钮和两层监听器分别复现配置问题、解释排查顺序。示例不接真实业务也不把构造的故障说成线上事故。版本与验证涉及的智慧手势接口起始版本为 26.0.0使用 Stage 模型。官方页面更新时间为 2026-08-29本次核对为 2026-09-27。本文 JavaScript 配置模型与断言已在本机 Node.js 执行ArkTS 接入代码未在 API 26 SDK 或真机编译运行设备端结果以下面的验收步骤核实不能用宿主测试替代。不要用选中框判断按钮能否响应官方对三个字段的分工很明确但名字容易让人读偏。配置负责什么排查时容易误解的地方enabled组件是否响应智慧手势不是 selectable 的别名缺省为 falseselectable组件被选中后是否显示并保留选中态false 不等于禁止响应action智慧手势响应优先级当前仅支持 GestureShortcut.PRIMARY不能凭空补一个 NORMAL 枚举selectable 的缺省值随 enabled 变化enabled 为 true 时缺省为 true否则缺省为 false。对需要稳定反馈的按钮直接写出两个字段比依赖缺省更容易审查。还有更外层的控制器。enableSmartTapAndSlideGestures(false) 关闭敲一敲、划一划的处理但组件属性仍保留它不影响翻腕手势。因此“组件上 enabled 已经是 true”并不足以证明整个处理链打开了。这些属性声明响应方式不会在配置时直接执行一次点击或滚动。也不能把“设置了 PRIMARY”解释成“该按钮必定唯一获选”官方完整示例对多个组件都设置了 PRIMARY并没有给出“一页多个 PRIMARY 就报错”的规定。应用可以主动收敛重要操作但那是产品策略不是平台限制。案例一没有选中框究竟是哪一个开关关了这个实验只保留一个目标按钮和一个点击计数。先固定页面、目标 ID 与点击回调只改变 enabled 和 selectable不要同时改控制器和业务逻辑。在 API 26 Stage 工程的入口页面中接入以下示例。使用 V2 状态管理目标按钮一直在可见区域内。下面的两个普通控制按钮只切配置不调用智慧手势提案。Entry ComponentV2 struct GestureProbe { Local respond: boolean true; Local retainSelection: boolean true; Local clicks: number 0; private controller this.getUIContext().getSmartGestureController(); aboutToAppear(): void { this.controller.enableSmartTapAndSlideGestures(true); } aboutToDisappear(): void { this.controller.clearSelected(); this.controller.enableSmartTapAndSlideGestures(false); } build() { Column({ space: 20 }) { Text(点击次数 this.clicks) Button(计数目标) .id(gesture_probe_target) .smartGestureShortcut({ action: GestureShortcut.PRIMARY, enabled: this.respond, selectable: this.retainSelection }) .onClick(() { this.clicks 1; }) Button(this.respond ? 关闭响应 : 开启响应) .onClick(() { this.respond !this.respond; }) Button(this.retainSelection ? 隐藏选中框 : 显示选中框) .onClick(() { this.retainSelection !this.retainSelection; }) Button(请求选中目标) .onClick(() { this.controller.requestSelected(gesture_probe_target); }) }.width(100%).padding(24) } }手指直接点击目标只验证 onClick 链路不能据此证明智慧手势正常。设备端应分别记录手势动作、选择提示和点击计数不把三件事合成一个“成功”标记。操作组合根据接口定义应核验的结果不能得出的结论控制器开启enabledtrueselectabletrue组件允许响应并启用选中态反馈不能保证每次手势都是点击动作保持 enabledtrue只改 selectablefalse关闭选中态反馈不应把它当响应禁用没选中框不等于目标不可响应保持 selectabletrue只改 enabledfalse目标组件不响应智慧手势selectabletrue 不能反向开启响应保持组件配置关闭控制器敲一敲、划一划停止处理配置仍在不能据此推断翻腕也被关闭requestSelected 是另一条显式选中请求。官方列出的生效条件包括目标允许响应、屏幕内可见、绑定 onClick 或单击 TapGesture。用它检查时先把 selectable 设回 true避免把显式选中和自动手势反馈混在一次实验里。列表复用、滚出屏幕或忘了点击回调时应先查这些前提不要不断增加延时。真实页面若共享同一个 UIContext不能照搬本例的“页面退出就全局关闭”。本例是一张独占实验页正式工程应由拥有该控制器使用权的页面容器或协调层统一启停避免子组件退出时关闭兄弟组件正在用的能力。用可执行模型锁住字段语义配置组合不依赖设备输入可以先在宿主环境回归。下面是应用侧的配置解释模型不是鸿蒙内部命中算法它只验证本文的字段理解不预测系统最终选中了哪个节点。将完整代码作为一个 .mjs 文件执行命令为 node 文件名.mjs。断言失败会直接退出。import assert from node:assert/strict; function describeOptions(options {}) { const enabled options.enabled ?? false; const showSelection options.selectable ?? enabled; return { enabled, showSelection }; } const enabledNoOutline describeOptions({ enabled: true, selectable: false }); assert.equal(enabledNoOutline.enabled, true); assert.equal(enabledNoOutline.showSelection, false); assert.deepEqual(describeOptions(), { enabled: false, showSelection: false }); assert.deepEqual(describeOptions({ enabled: true }), { enabled: true, showSelection: true }); assert.equal(describeOptions({ selectable: true }).enabled, false); console.log(option checks passed);如果测试写成 nodes.filter(node node.selectable)它验证的就是错误前提把选中框开关拿去过滤响应节点。这里没有“测试通过就万事大吉”测试本身必须先对齐官方定义。案例二新增弹层监听后底层页面为什么收不到这次不改按钮属性只改变监听器。先注册页面监听 A再注册弹层监听 B。官方规定后注册的先执行某个回调返回的 GestureHandlingResolution.isConsumed 为 true 时后续监听不再执行。所以 B 先执行并消费A 没收到并不能说明 A 注册失败。反过来如果 B 只观察、不接管返回 false让监听链继续处理。还要分清“消费”和“取消动作”new GestureHandlingResolution(true) 没有设置 selectedProposal 时沿用系统默认处理不是把手势吞掉后什么也不做。要替换成不执行动作需要一个合法的 NoneActionProposal返回普通对象也不能代替官方结果类。下面的测试模型只模拟后注册先执行以及消费截断使用字符串表示替换结果不是可以返回给 ArkUI 的对象。完整执行后输出 monitor checks passed。import assert from node:assert/strict; function dispatch(monitors, proposal) { const visited []; for (let i monitors.length - 1; i 0; i - 1) { const monitor monitors[i]; visited.push(monitor.id); const result monitor.handle(proposal); if (result.isConsumed) { return { visited, consumed: true, action: result.selectedProposal ?? proposal }; } } return { visited, consumed: false, action: null }; } const page { id: page, handle: () ({ isConsumed: true }) }; const overlay { id: overlay, handle: () ({ isConsumed: true, selectedProposal: NONE }) }; assert.deepEqual(dispatch([page, overlay], CLICK), { visited: [overlay], consumed: true, action: NONE }); const observer { id: observer, handle: () ({ isConsumed: false, selectedProposal: IGNORED }) }; assert.deepEqual(dispatch([page, observer], CLICK), { visited: [observer, page], consumed: true, action: CLICK }); assert.deepEqual(dispatch([observer], CLICK), { visited: [observer], consumed: false, action: null }); console.log(monitor checks passed);接回 ArkTS 时回调必须返回 kit.ArkUI 导出的 GestureHandlingResolution 实例。保存回调函数引用再把同一个引用交给 registerMonitor 与 unregisterMonitor。不要在注册和注销时各写一个内容一样的新箭头函数它们不是同一个函数对象。一个只记录而不消费的监听器可以写成import { BaseGestureHandlingProposal, GestureHandlingResolution } from kit.ArkUI; const observer (proposal: BaseGestureHandlingProposal): GestureHandlingResolution { console.info(gesture action proposal.action); return new GestureHandlingResolution(false); }; // 由拥有当前 UIContext 的组件执行 // controller.registerMonitor(observer); // 该组件退出时执行 // controller.unregisterMonitor(observer);组件退出优先注销自己的回调。clearMonitors 会清空当前 UIContext 的全部监听器不能当成“顺便清理我自己”的快捷方式。只有统一拥有这些监听器的协调层才适合执行整组清理。选哪种修法取决于故障层级仅缺选中反馈就查 selectable 和选中态不增加一个全局监听器。目标根本不响应就查 enabled、控制器启用范围及目标可见性。目标选择需要业务干预时再接 registerMonitor并明确谁消费、是否替换默认动作。这比所有页面都拦截手势更容易维护普通按钮仍交给系统处理少数特殊页面才拥有干预逻辑。代价是要把共享 UIContext 的控制权分配好否则一个组件的清理会影响另一个组件。上线前保留三类证据配置组合表、监听执行顺序、设备端动作和画面。至少跑一次“进入页面—打开弹层—关闭弹层—退出—重新进入”确认没有残留监听再跑 enabledtrue/selectablefalse 组合确认团队不会继续把没有边框当成禁用。官方参考智慧手势响应smartGestureShortcut 与字段缺省值SmartGestureController启停、监听顺序、requestSelected 条件GestureHandlingResolution消费与替换动作这三个页面都应按当前目标 SDK 再核对一遍。本文的重点不是给所有智慧手势问题套一个状态机而是先把响应、选中反馈、监听消费拆成三个可以分别验证的事实。
HarmonyOS 7 智慧手势不响应先查 enabled、selectable再查监听器有没有截走动作给按钮加了智慧手势属性画面没有选中框就认定接口没生效于是又注册一个监听器结果另一个页面的监听也收不到动作。这两种现象看起来都是“手势失灵”查的却不是同一层前者要区分响应开关和视觉反馈后者要看监听顺序与消费结果。下面用一个计数按钮和两层监听器分别复现配置问题、解释排查顺序。示例不接真实业务也不把构造的故障说成线上事故。版本与验证涉及的智慧手势接口起始版本为 26.0.0使用 Stage 模型。官方页面更新时间为 2026-08-29本次核对为 2026-09-27。本文 JavaScript 配置模型与断言已在本机 Node.js 执行ArkTS 接入代码未在 API 26 SDK 或真机编译运行设备端结果以下面的验收步骤核实不能用宿主测试替代。不要用选中框判断按钮能否响应官方对三个字段的分工很明确但名字容易让人读偏。配置负责什么排查时容易误解的地方enabled组件是否响应智慧手势不是 selectable 的别名缺省为 falseselectable组件被选中后是否显示并保留选中态false 不等于禁止响应action智慧手势响应优先级当前仅支持 GestureShortcut.PRIMARY不能凭空补一个 NORMAL 枚举selectable 的缺省值随 enabled 变化enabled 为 true 时缺省为 true否则缺省为 false。对需要稳定反馈的按钮直接写出两个字段比依赖缺省更容易审查。还有更外层的控制器。enableSmartTapAndSlideGestures(false) 关闭敲一敲、划一划的处理但组件属性仍保留它不影响翻腕手势。因此“组件上 enabled 已经是 true”并不足以证明整个处理链打开了。这些属性声明响应方式不会在配置时直接执行一次点击或滚动。也不能把“设置了 PRIMARY”解释成“该按钮必定唯一获选”官方完整示例对多个组件都设置了 PRIMARY并没有给出“一页多个 PRIMARY 就报错”的规定。应用可以主动收敛重要操作但那是产品策略不是平台限制。案例一没有选中框究竟是哪一个开关关了这个实验只保留一个目标按钮和一个点击计数。先固定页面、目标 ID 与点击回调只改变 enabled 和 selectable不要同时改控制器和业务逻辑。在 API 26 Stage 工程的入口页面中接入以下示例。使用 V2 状态管理目标按钮一直在可见区域内。下面的两个普通控制按钮只切配置不调用智慧手势提案。Entry ComponentV2 struct GestureProbe { Local respond: boolean true; Local retainSelection: boolean true; Local clicks: number 0; private controller this.getUIContext().getSmartGestureController(); aboutToAppear(): void { this.controller.enableSmartTapAndSlideGestures(true); } aboutToDisappear(): void { this.controller.clearSelected(); this.controller.enableSmartTapAndSlideGestures(false); } build() { Column({ space: 20 }) { Text(点击次数 this.clicks) Button(计数目标) .id(gesture_probe_target) .smartGestureShortcut({ action: GestureShortcut.PRIMARY, enabled: this.respond, selectable: this.retainSelection }) .onClick(() { this.clicks 1; }) Button(this.respond ? 关闭响应 : 开启响应) .onClick(() { this.respond !this.respond; }) Button(this.retainSelection ? 隐藏选中框 : 显示选中框) .onClick(() { this.retainSelection !this.retainSelection; }) Button(请求选中目标) .onClick(() { this.controller.requestSelected(gesture_probe_target); }) }.width(100%).padding(24) } }手指直接点击目标只验证 onClick 链路不能据此证明智慧手势正常。设备端应分别记录手势动作、选择提示和点击计数不把三件事合成一个“成功”标记。操作组合根据接口定义应核验的结果不能得出的结论控制器开启enabledtrueselectabletrue组件允许响应并启用选中态反馈不能保证每次手势都是点击动作保持 enabledtrue只改 selectablefalse关闭选中态反馈不应把它当响应禁用没选中框不等于目标不可响应保持 selectabletrue只改 enabledfalse目标组件不响应智慧手势selectabletrue 不能反向开启响应保持组件配置关闭控制器敲一敲、划一划停止处理配置仍在不能据此推断翻腕也被关闭requestSelected 是另一条显式选中请求。官方列出的生效条件包括目标允许响应、屏幕内可见、绑定 onClick 或单击 TapGesture。用它检查时先把 selectable 设回 true避免把显式选中和自动手势反馈混在一次实验里。列表复用、滚出屏幕或忘了点击回调时应先查这些前提不要不断增加延时。真实页面若共享同一个 UIContext不能照搬本例的“页面退出就全局关闭”。本例是一张独占实验页正式工程应由拥有该控制器使用权的页面容器或协调层统一启停避免子组件退出时关闭兄弟组件正在用的能力。用可执行模型锁住字段语义配置组合不依赖设备输入可以先在宿主环境回归。下面是应用侧的配置解释模型不是鸿蒙内部命中算法它只验证本文的字段理解不预测系统最终选中了哪个节点。将完整代码作为一个 .mjs 文件执行命令为 node 文件名.mjs。断言失败会直接退出。import assert from node:assert/strict; function describeOptions(options {}) { const enabled options.enabled ?? false; const showSelection options.selectable ?? enabled; return { enabled, showSelection }; } const enabledNoOutline describeOptions({ enabled: true, selectable: false }); assert.equal(enabledNoOutline.enabled, true); assert.equal(enabledNoOutline.showSelection, false); assert.deepEqual(describeOptions(), { enabled: false, showSelection: false }); assert.deepEqual(describeOptions({ enabled: true }), { enabled: true, showSelection: true }); assert.equal(describeOptions({ selectable: true }).enabled, false); console.log(option checks passed);如果测试写成 nodes.filter(node node.selectable)它验证的就是错误前提把选中框开关拿去过滤响应节点。这里没有“测试通过就万事大吉”测试本身必须先对齐官方定义。案例二新增弹层监听后底层页面为什么收不到这次不改按钮属性只改变监听器。先注册页面监听 A再注册弹层监听 B。官方规定后注册的先执行某个回调返回的 GestureHandlingResolution.isConsumed 为 true 时后续监听不再执行。所以 B 先执行并消费A 没收到并不能说明 A 注册失败。反过来如果 B 只观察、不接管返回 false让监听链继续处理。还要分清“消费”和“取消动作”new GestureHandlingResolution(true) 没有设置 selectedProposal 时沿用系统默认处理不是把手势吞掉后什么也不做。要替换成不执行动作需要一个合法的 NoneActionProposal返回普通对象也不能代替官方结果类。下面的测试模型只模拟后注册先执行以及消费截断使用字符串表示替换结果不是可以返回给 ArkUI 的对象。完整执行后输出 monitor checks passed。import assert from node:assert/strict; function dispatch(monitors, proposal) { const visited []; for (let i monitors.length - 1; i 0; i - 1) { const monitor monitors[i]; visited.push(monitor.id); const result monitor.handle(proposal); if (result.isConsumed) { return { visited, consumed: true, action: result.selectedProposal ?? proposal }; } } return { visited, consumed: false, action: null }; } const page { id: page, handle: () ({ isConsumed: true }) }; const overlay { id: overlay, handle: () ({ isConsumed: true, selectedProposal: NONE }) }; assert.deepEqual(dispatch([page, overlay], CLICK), { visited: [overlay], consumed: true, action: NONE }); const observer { id: observer, handle: () ({ isConsumed: false, selectedProposal: IGNORED }) }; assert.deepEqual(dispatch([page, observer], CLICK), { visited: [observer, page], consumed: true, action: CLICK }); assert.deepEqual(dispatch([observer], CLICK), { visited: [observer], consumed: false, action: null }); console.log(monitor checks passed);接回 ArkTS 时回调必须返回 kit.ArkUI 导出的 GestureHandlingResolution 实例。保存回调函数引用再把同一个引用交给 registerMonitor 与 unregisterMonitor。不要在注册和注销时各写一个内容一样的新箭头函数它们不是同一个函数对象。一个只记录而不消费的监听器可以写成import { BaseGestureHandlingProposal, GestureHandlingResolution } from kit.ArkUI; const observer (proposal: BaseGestureHandlingProposal): GestureHandlingResolution { console.info(gesture action proposal.action); return new GestureHandlingResolution(false); }; // 由拥有当前 UIContext 的组件执行 // controller.registerMonitor(observer); // 该组件退出时执行 // controller.unregisterMonitor(observer);组件退出优先注销自己的回调。clearMonitors 会清空当前 UIContext 的全部监听器不能当成“顺便清理我自己”的快捷方式。只有统一拥有这些监听器的协调层才适合执行整组清理。选哪种修法取决于故障层级仅缺选中反馈就查 selectable 和选中态不增加一个全局监听器。目标根本不响应就查 enabled、控制器启用范围及目标可见性。目标选择需要业务干预时再接 registerMonitor并明确谁消费、是否替换默认动作。这比所有页面都拦截手势更容易维护普通按钮仍交给系统处理少数特殊页面才拥有干预逻辑。代价是要把共享 UIContext 的控制权分配好否则一个组件的清理会影响另一个组件。上线前保留三类证据配置组合表、监听执行顺序、设备端动作和画面。至少跑一次“进入页面—打开弹层—关闭弹层—退出—重新进入”确认没有残留监听再跑 enabledtrue/selectablefalse 组合确认团队不会继续把没有边框当成禁用。官方参考智慧手势响应smartGestureShortcut 与字段缺省值SmartGestureController启停、监听顺序、requestSelected 条件GestureHandlingResolution消费与替换动作这三个页面都应按当前目标 SDK 再核对一遍。本文的重点不是给所有智慧手势问题套一个状态机而是先把响应、选中反馈、监听消费拆成三个可以分别验证的事实。
