物理按键监听
HAC 中监听、停止监听物理按键的流程、生命周期和误触防护。
适用场景
物理按键监听用于在 HAC 中接收 Android 设备或 PDA 的实体按键事件，并在按下指定按键时执行子命令。
适合把高频动作从触屏转移到实体按键，例如确认、提交、切换数量、打开异常登记、触发扫码前置逻辑。戴手套、单手握持、强光环境和连续作业场景尤其适合使用。
使用前提
- 应用运行在
HAC中； - 当前设备有可监听的实体按键；
- 按键码、覆盖行为和厂商实现已在真机验证；
- 页面已定义按键触发时的业务状态校验和防重复提交；
- 离开页面、打开弹窗或任务完成时有停止监听逻辑。
命令速查
| 命令 | 类型 | 用途 |
|---|---|---|
| 开始监听物理按键 | 异步 | 监听指定按键，按下后执行子命令 |
| 停止监听指定物理按键 | 普通命令 | 停止某一个按键监听 |
| 停止监听所有物理按键 | 普通命令 | 清理当前流程中的全部监听 |
可监听按键包括菜单、返回、主页、搜索、音量、电源、相机、电话、方向键、中央选择键、数字键、星号键和井号键。
推荐流程
进入作业页面
-> 判断当前是否在 HAC 中
-> 初始化页面状态
-> 执行【开始监听物理按键】
-> 用户按下按键
-> 子命令先校验当前状态
-> 校验通过：提交、切换或跳转
-> 校验失败：提示原因，不改变关键状态
-> 离开页面 / 任务完成 / 异常退出
-> 停止指定按键或停止全部按键监听覆盖原有操作
【开始监听物理按键】可配置是否覆盖按键原有操作。
| 配置 | 行为 |
|---|---|
| 不覆盖 | 系统原行为仍可能发生，同时触发监听逻辑 |
| 覆盖 | 原行为被拦截，优先执行插件子命令 |
谨慎覆盖
音量键、返回键等系统常用按键被覆盖后，用户可能无法完成原本操作。只在明确的作业页覆盖，并在离开页面时恢复。
设计要点
- 页面上仍保留可点击按钮，作为触屏备用入口；
- 显示当前按键含义，例如“确认键：提交当前项”；
- 按键触发提交类动作时，必须做防重复提交；
- 危险或不可逆操作不要由按键直接执行，可先打开确认界面；
- 打开弹窗、拍照、PDF、电话、APP 设置页前，暂停或清理相关监听；
- 多个按键同时使用时，避免不同按键竞争同一个页面状态。
异常处理
| 异常 | 常见原因 | 推荐处理 |
|---|---|---|
| 按键无反应 | 未在 HAC 中、按键配置错误、监听未启动 | 提示检查环境和配置，允许重新启动监听 |
| 触发错误动作 | 重复注册、子命令配置错误 | 停止所有监听后重新注册 |
| 系统操作被拦截 | 勾选了覆盖原有操作 | 离开页面时停止监听，并提示当前按键被接管 |
| 连续触发多次 | 长按、设备重复上报、子命令执行慢 | 增加防抖、执行中锁定和幂等校验 |
| 弹窗中仍响应旧按键 | 弹窗前未暂停监听 | 打开弹窗前停止，关闭后按需恢复 |
| 离开页面后仍触发 | 未绑定生命周期 | 页面离开、任务完成、异常恢复时执行停止命令 |