鸿蒙系统 keycodeType 详解与 hdc 发送按键控制设备

~远在太平洋~

206人浏览 · 2026-08-11 20:18:58

~远在太平洋~ · 2026-08-11 20:18:58 发布

适用对象：需要理解鸿蒙按键码、并通过 hdc 远程控制设备按键的新人
文档定位：概念讲清 + 两套 keycode 体系避坑 + hdc 发送按键直接抄
配套文档：hdc 环境配置 · wukong 测试 · hilog 使用指南

一、keycodeType 是什么（30 秒理解）

在鸿蒙多模输入里，一次按键事件由两个核心要素组成：

要素	含义	举例
keyCode（键值）	标识"按了哪个键"的数字	Home=1、Back=2、音量+=16（应用层枚举值）
keyType / action（按键类型·动作）	标识"按下还是抬起"	`DOWN`（按下）、`UP`（抬起）、`CANCEL`（取消）

所谓 keycodeType，可理解为"按键码 + 按键动作类型"的统称。一次普通点击 = 一次 DOWN + 一次 UP；长按 = DOWN 后延时再 UP。

应用层在 ArkTS 里收到的事件对象 KeyEvent 就包含 keyCode 和 action（还有 keyText 按键字符等）。

二、⚠️ 最关键的坑：两套 keycode 体系（必看！）

鸿蒙里**"发送端"和"接收端"用的是两套完全不同的数字**，这是新人 90% confusion 的来源：

场景	用的 keycode 体系	Home 的值	Back 的值	音量+ 的值	电源的值
hdc `input keyevent` 注入（发送端）	Android 风格底层 keycode	`3`	`4`	`24`	`25`
ArkTS 应用 `KeyCode` 枚举（接收端）	OpenHarmony 多模输入枚举	`1`	`2`	`16`	`17`

为什么会这样？ input keyevent 是 Linux/Android 兼容注入层，直接注入底层 keycode；多模输入服务（MMI）收到后会把它映射成 OpenHarmony 自己的 KeyCode 枚举再派发给应用。所以：

你用 hdc shell input keyevent 3 发 Home → 应用里 onKeyEvent 收到的 keyCode 是 1（KEYCODE_HOME）。

记忆口诀：发用 3，收用 1；底层 Android 数，应用 OpenHarmony 值。搞混就按不出想要的键。

三、KeyCode 枚举详解（应用层 `@ohos.multimodalInput.keyCode`）

来源模块 @kit.InputKit，API 9+ 支持，按键设备（键盘/电源/拍照等）的键值。

导入：import { KeyCode } from '@kit.InputKit';
系统能力：SystemCapability.MultimodalInput.Input.Core

数值分段规律

区间	含义
`-1`	`KEYCODE_UNKNOWN` 未知按键
`0`	`KEYCODE_FN` 功能键
`1 ~ 999`	系统/功能键（Home、Back、音量、电源、媒体等）
`2000 ~ 2099`	字母/数字/符号/方向/修饰键
`2100 ~ 2199`	小键盘、F1~F12、锁键
`2200+`	设备特有键、游戏手柄、TV、车机等

常用按键对照表（应用层枚举值 —— 写代码时用）

按键	枚举名	值	按键	枚举名	值
Home	`KEYCODE_HOME`	1	回车	`KEYCODE_ENTER`	2054
Back	`KEYCODE_BACK`	2	退格	`KEYCODE_DEL`	2055
搜索	`KEYCODE_SEARCH`	9	空格	`KEYCODE_SPACE`	2050
音量+	`KEYCODE_VOLUME_UP`	16	Tab	`KEYCODE_TAB`	2049
音量-	`KEYCODE_VOLUME_DOWN`	17	菜单	`KEYCODE_MENU`	2067
电源	`KEYCODE_POWER`	18	Esc	`KEYCODE_ESCAPE`	2070
拍照	`KEYCODE_CAMERA`	19	方向↑	`KEYCODE_DPAD_UP`	2012
静音(扬)	`KEYCODE_VOLUME_MUTE`	22	方向↓	`KEYCODE_DPAD_DOWN`	2013
调亮	`KEYCODE_BRIGHTNESS_UP`	40	方向←	`KEYCODE_DPAD_LEFT`	2014
数字0~9	`KEYCODE_0`~`KEYCODE_9`	2000~2009	方向→	`KEYCODE_DPAD_RIGHT`	2015
字母A~Z	`KEYCODE_A`~`KEYCODE_Z`	2017~2042	确定	`KEYCODE_DPAD_CENTER`	2016

完整清单见华为官方 KeyCode 参考。不同 API 版本会新增枚举（如游戏手柄、智感键、TV 键等），以设备实际版本为准。

四、按键动作类型（keyType / action）

动作	含义	触发时机
`DOWN`	按下	手指/按键接触瞬间
`UP`	抬起	松开瞬间
`CANCEL`	取消	事件被系统中断
`UNKNOWN`	未知	异常

应用层监听示例（ArkTS）：

onKeyEvent((event: KeyEvent) => {
  if (event.action === KeyAction.DOWN && event.keyCode === KeyCode.KEYCODE_BACK) {
    // 按下了返回键
  }
})

五、hdc 发送按键控制设备的三种方式

方式 1：`input keyevent`（底层数字 / 名称）—— 最通用

# 语法
hdc shell input keyevent <keycode数字或名称>

# 常用（底层 Android 风格数字，注意不是应用层枚举值！）
hdc shell input keyevent 3        # Home / 返回桌面
hdc shell input keyevent 4        # Back / 返回上一级
hdc shell input keyevent 24       # 音量 +
hdc shell input keyevent 25       # 音量 -
hdc shell input keyevent 26       # 电源键
hdc shell input keyevent 66       # 回车 Enter
hdc shell input keyevent 82       # 菜单 Menu
hdc shell input keyevent 19       # 方向键 上
hdc shell input keyevent 23       # 方向键 确定(中心)

底层 keycode 常用对照（Android 风格，input 命令用这套）

按键	数字	按键	数字
HOME	3	VOLUME_UP	24
BACK	4	VOLUME_DOWN	25
DPAD_UP	19	POWER	26
DPAD_DOWN	20	CAMERA	27
DPAD_LEFT	21	ENTER	66
DPAD_RIGHT	22	MENU	82
DPAD_CENTER	23	VOLUME_MUTE	164

部分版本支持直接写名称（如 input keyevent KEYCODE_HOME），但数字最稳，建议用数字。

方式 2：`uitest uiinput keyevent`（名称，推荐新手）

OpenHarmony 的 uitest UI 测试框架提供更直观的按键名方式，不用记数字：

hdc shell uitest uiinput keyevent home          # 返回桌面
hdc shell uitest uiinput keyevent back          # 返回上一级
hdc shell uitest uiinput keyevent volume_up     # 音量 +
hdc shell uitest uiinput keyevent volume_down   # 音量 -
hdc shell uitest uiinput keyevent power          # 电源
hdc shell uitest uiinput keyevent menu          # 菜单

uitest 需设备已开启开发者选项 + USB 调试；名称不支持时回退到方式 1。

方式 3：wukong 随机键盘注入（压力测试用）

不需要指定具体键，让 wukong 随机注入键盘事件（见 wukong 笔记 -k 参数）：

hdc shell
wukong exec -b com.example.myapp -k 0.1 -c 100   # 10% 键盘事件比例

六、实战模板（直接抄）

# 1. 一键回桌面（最常用）
hdc shell input keyevent 3

# 2. 返回上一级
hdc shell input keyevent 4
# 或 hdc shell uitest uiinput keyevent back

# 3. 音量加 3 次（循环）
for i in 1 2 3; do hdc shell input keyevent 24; sleep 0.3; done

# 4. 锁屏（电源键）
hdc shell input keyevent 26

# 5. 在输入框里打字（先聚焦输入框，再发字母/回车）
hdc shell input keyevent 2017   # A
hdc shell input keyevent 2054   # 回车

# 6. 配合 wukong 压测时实时盯按键相关日志
hdc shell hilog -L I | grep -i key

七、与 wukong / hilog 配合（实战闭环）

# 终端 A：跑压测（含键盘事件）
hdc shell
wukong exec -b com.example.myapp -k 0.15 -t 0.6 -a 0.25 -T 20

# 终端 B：盯按键/系统键日志，排查按键异常
hdc shell hilog | grep -iE "key|keycode"

# 压测后回桌面、抓日志留证
hdc shell input keyevent 3
hdc file recv /data/log/hilog/ ./logs
hilogtool parse -i ./logs -d ./logs

八、⚠️ 新手必踩的 5 个坑

用错 keycode 体系 → 想发 Home 却写成 input keyevent 1（那是应用层枚举值），设备没反应。注入端用 Android 数字 3，不是应用层 1。见第二节。
数字 3 没反应 → 设备可能未开 USB 调试，或 uitest/注入被系统限制（部分系统键需特定权限/root）。
uitest 命令不存在 → 老版本/精简系统没预置 uitest，回退用 input keyevent 数字方式。
长按/组合键失效 → 单次 input keyevent 是"按下+抬起"一起完成。要长按需分别发 DOWN/UP 并延时，或加 --longpress（视版本支持）。
系统键不响应（电源/音量） → 这些是系统功能键，部分设备对注入有权限约束；优先用 uitest uiinput keyevent 名称方式，成功率更高。

记忆口诀：发用 3，收用 1；底层 Android 数，应用 OpenHarmony 值。搞混就按不出想要的键。

九、标准作业流（SOP）

1. hdc 已配通（见配套文档），设备开 USB 调试
2. 想发系统键 → 优先 `hdc shell uitest uiinput keyevent <名称>`
3. 名称不支持 → `hdc shell input keyevent <Android数字>`
4. 不确定数字 → 查本文"底层 keycode 对照表"（Home=3/Back=4/Vol+=24...）
5. 写应用代码监听时 → 用 @ohos.multimodalInput.keyCode 枚举（HOME=1/BACK=2...）
6. 异常排查 → hdc shell hilog | grep key

十、一句话速记卡（贴显示器上）

keycodeType = 按键码(keyCode) + 动作类型(DOWN/UP)
两套体系:
  发(hdc input keyevent) → Android数: Home=3 Back=4 Vol+=24 Vol-=25 Power=26
  收(App KeyCode)        → OH枚举:   Home=1 Back=2 Vol+=16 Vol-=17 Power=18

发送按键:
  hdc shell input keyevent 3              ← Home(底层数)
  hdc shell uitest uiinput keyevent home  ← 名称(推荐)
  wukong -k 0.15 ...                      ← 随机键盘压测

写代码监听: import { KeyCode } from '@kit.InputKit'

参考来源

华为开发者文档：@ohos.multimodalInput.keyCode（键值）官方参考
华为开发者文档：支持键盘输入事件（KeyEvent / action）
实践参考：hdc shell input keyevent 3 返回桌面、uitest uiinput keyevent home/back（社区验证）