HarmonyOS 7 智慧手势不响应？先查 enabled、selectable，再查监听器有没有截走动作

给按钮加了智慧手势属性，画面没有选中框，就认定接口没生效；于是又注册一个监听器，结果另一个页面的监听也收不到动作。这两种现象看起来都是“手势失灵”，查的却不是同一层：前者要区分响应开关和视觉反馈，后者要看监听顺序与消费结果。

下面用一个计数按钮和两层监听器分别复现配置问题、解释排查顺序。示例不接真实业务，也不把构造的故障说成线上事故。

版本与验证：涉及的智慧手势接口起始版本为 26.0.0，使用 Stage 模型。官方页面更新时间为 2026-08-29，本次核对为 2026-09-27。本文 JavaScript 配置模型与断言已在本机 Node.js 执行；ArkTS 接入代码未在 API 26 SDK 或真机编译运行，设备端结果以下面的验收步骤核实，不能用宿主测试替代。

不要用选中框判断按钮能否响应

官方对三个字段的分工很明确，但名字容易让人读偏。

配置	负责什么	排查时容易误解的地方
enabled	组件是否响应智慧手势	不是 selectable 的别名；缺省为 false
selectable	组件被选中后是否显示并保留选中态	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 链路，不能据此证明智慧手势正常。设备端应分别记录手势动作、选择提示和点击计数，不把三件事合成一个“成功”标记。

操作组合	根据接口定义应核验的结果	不能得出的结论
控制器开启，enabled=true，selectable=true	组件允许响应并启用选中态反馈	不能保证每次手势都是点击动作
保持 enabled=true，只改 selectable=false	关闭选中态反馈，不应把它当响应禁用	没选中框不等于目标不可响应
保持 selectable=true，只改 enabled=false	目标组件不响应智慧手势	selectable=true 不能反向开启响应
保持组件配置，关闭控制器	敲一敲、划一划停止处理，配置仍在	不能据此推断翻腕也被关闭

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 的控制权分配好，否则一个组件的清理会影响另一个组件。

上线前保留三类证据：配置组合表、监听执行顺序、设备端动作和画面。至少跑一次“进入页面—打开弹层—关闭弹层—退出—重新进入”，确认没有残留监听；再跑 enabled=true/selectable=false 组合，确认团队不会继续把没有边框当成禁用。

官方参考

• 智慧手势响应：smartGestureShortcut 与字段缺省值
• SmartGestureController：启停、监听顺序、requestSelected 条件
• GestureHandlingResolution：消费与替换动作

这三个页面都应按当前目标 SDK 再核对一遍。本文的重点不是给所有智慧手势问题套一个状态机，而是先把响应、选中反馈、监听消费拆成三个可以分别验证的事实。