HarmonyOS 7 智慧手势选错按钮？smartGestureShortcut 三个参数的优先级边界

给组件设置 enabled=true 后，系统并不会替应用自动完成点击、滚动或翻页。smartGestureShortcut 声明的是组件是否进入智慧手势候选、是否保留选中态和响应优先级，业务动作仍需要在处理路径中校验并执行。

先确认 API 26 的能力边界

官方 API 参考显示 smartGestureShortcut 从 26.0.0 开始支持，Stage 模型可用。enabled 默认 false；selectable 在启用时默认 true；action 当前支持 PRIMARY。官方建议显式传入，避免缺省值造成预期差异。

• enabled 只声明响应资格，不直接触发业务动作。
• selectable 是手势选中视觉态，不等于业务选中字段。
• 多个候选都设为 PRIMARY 时，应用仍要收紧可用候选。

案例一：enabled 已开启，业务按钮仍然没有执行

候选状态和执行状态必须分开。手势 proposal 到达后还要检查页面代际、目标 id 和幂等状态。

type Result = 'done' | 'stale' | 'busy'
class GestureExecutor {
  private generation = 0; private running = false
  updatePage(): void { this.generation += 1 }
  async execute(generation: number, action: () => Promise<void>): Promise<Result> {
    if (generation !== this.generation) return 'stale'
    if (this.running) return 'busy'
    this.running = true
    try { await action(); return 'done' } finally { this.running = false }
  }
}

页面切换后的迟到动作被拒绝，连续识别也不会重复提交同一操作。

案例二：一屏多个按钮都成为 PRIMARY，目标选择不稳定

应用应先根据可见比例、安全状态和页面模式选出主候选，再给不可用组件设置 enabled=false。

interface Candidate { id: string; enabled: boolean; visible: number; blocked: boolean; rank: number }
function choose(items: Candidate[]): Candidate | undefined {
  return items.filter(item => item.enabled && !item.blocked && item.visible >= 0.6)
    .sort((a, b) => b.rank - a.rank)[0]
}
const picked = choose([{ id: 'play', enabled: true, visible: 1, blocked: false, rank: 100 },
  { id: 'delete', enabled: true, visible: 1, blocked: true, rank: 200 }])
console.assert(picked?.id === 'play')

危险或不可用操作即使 rank 更高也不会成为目标，可见区域变化后重新计算候选。

现象与判断对照

现象	优先检查	处理原则
开启后没有点击	是否把声明当成执行	接入动作处理路径
多个按钮都被选中	候选是否过宽	只启用当前可用目标
弹窗出现仍操作背景	页面模式是否参与筛选	禁用背景候选
退出后仍保留高亮	视觉态是否独立清理	与业务选中分离

为什么选择这个实现

显式配置三个字段，再用候选策略控制 enabled，比把所有重要按钮都声明为 PRIMARY 更可预测。

可复用边界

候选选择器可以复用到播放器、阅读器和大屏应用；业务动作执行器继续负责代际和幂等，不与 ArkUI 属性耦合。

验证记录

已验证迟到 proposal 返回 stale、并发动作返回 busy、被阻断的高 rank 候选不会胜出，以及手势高亮清除不改变业务选中。

本文的策略代码已在宿主 JavaScript 环境执行断言，用来验证状态、排序、去重或边界计算。它不等同于 HarmonyOS 7 API 26 工程编译，也不等同于真机系统能力验证；涉及系统回调、设备能力、窗口形态或跨应用 IPC 的部分，仍应在对应 SDK 与设备上完成端到端验收。

上线前检查清单

• API 26 与 Stage 模型边界确认
• 三个字段显式设置
• 候选随可见区域更新
• 弹窗时禁用背景候选
• 动作执行有代际和幂等保护
• 触摸与键盘降级路径可用

官方资料

• smartGestureShortcut API 参考
• BaseGestureHandlingProposal API 参考

智慧手势属性负责声明目标，业务代码负责执行动作。把候选、视觉态和业务提交拆开，才不会出现“选中了却没执行”或“执行错按钮”。