引言现代设备早已不是一块屏幕那么简单。一台 HarmonyOS 设备可能同时连接着物理键盘、蓝牙鼠标、触控笔、游戏手柄甚至通过分布式能力使用其他设备的输入外设。对于应用开发者来说感知这些输入设备的存在、类型和状态变化能够打造更智能的交互体验——比如检测到键盘连接时显示快捷键提示检测到手写笔时开启精细绘图模式或者在用户长时间未操作后进入省电状态。HarmonyOS NEXT 通过ohos.multimodalInput.inputDevice模块提供了完整的输入设备管理能力。本文将构建一个输入设备实验室Demo展示设备枚举、信息查询、键盘类型检测、空闲计时器和热插拔事件监听的完整用法。读完本文你将掌握设备枚举getDeviceList()获取所有已连接输入设备设备信息getDeviceInfoSync()读取设备的名称、类型、厂商、总线等详细属性键盘类型检测getKeyboardTypeSync()识别字母键盘、数字键盘、手写笔等空闲计时getIntervalSinceLastInput()获取距离上次用户操作的毫秒数热插拔监听on(change)实时感知设备的插入与拔出环境与权限ohos.multimodalInput.inputDevice属于InputKit工具包自 API 8 开始提供。不需要申请任何权限即可使用。importinputDevicefromohos.multimodalInput.inputDevice;这是系统级 API 中少数零权限门槛的模块之一直接导入即用。一、核心数据类型InputDeviceData — 设备信息interfaceInputDeviceData{id:number;// 设备唯一ID重新插拔后可能变化name:string;// 设备名称如 HID Keyboardsources:ArraySourceType;// 输入源列表一个设备可能有多个输入源axisRanges:ArrayAxisRange;// 轴信息鼠标移动范围、触控区域等bus:number;// 总线类型product:number;// 产品IDvendor:number;// 厂商IDversion:number;// 版本号}注意sources是一个数组——一个物理设备可以同时支持多种输入方式。例如带触控板的键盘会同时有keyboard和touchpad两个 SourceType。SourceType — 输入源类型typeSourceTypekeyboard|mouse|touchpad|touchscreen|joystick|trackball;这是一个字符串联合类型不是枚举因此直接使用字符串字面量进行比较。KeyboardType — 键盘类型枚举enumKeyboardType{NONE0,// 无键盘UNKNOWN1,// 未知类型ALPHABETIC_KEYBOARD2,// 全字母键盘QWERTY等DIGITAL_KEYBOARD3,// 数字键盘小键盘HANDWRITING_PEN4,// 手写笔REMOTE_CONTROL5// 遥控器}DeviceListener — 热插拔事件数据typeDeviceListener{type:add|remove;// 事件类型插入或拔出deviceId:number;// 受影响的设备ID};二、设备枚举发现所有已连接输入设备获取设备列表采用异步 Promise 模式importinputDevicefromohos.multimodalInput.inputDevice;// 获取所有设备ID列表inputDevice.getDeviceList().then((deviceIds:Arraynumber){console.log(发现 deviceIds.length 个输入设备);// 遍历每个设备获取详细信息for(leti0;ideviceIds.length;i){letdeviceIddeviceIds[i];letinfo:inputDevice.InputDeviceDatainputDevice.getDeviceInfoSync(deviceId);console.log(设备名称: info.name);console.log(设备ID: info.id);// 解析输入源类型for(lets0;sinfo.sources.length;s){letsourceinfo.sources[s];if(sourcekeyboard){console.log( - 键盘输入);}elseif(sourcemouse){console.log( - 鼠标输入);}elseif(sourcetouchscreen){console.log( - 触摸屏输入);}}}}).catch((err:Error){console.error(获取设备列表失败: err.message);});getDeviceList 返回的是什么返回一个Arraynumber仅包含设备 ID。要获取设备的详细信息需要用这些 ID 逐个调用getDeviceInfo()。为什么用 getDeviceInfoSync 而不是 Promise 版本getDeviceList()返回 ID 后需要立即获取每个设备的详细信息。如果对列表中的每个设备都发起异步请求代码结构会比较复杂需要Promise.all包装。而getDeviceInfoSync()可以直接在同步循环中调用代码更清晰。三、设备热插拔实时感知插拔事件这是 inputDevice 模块最实用的功能之一。通过on(change)注册监听当用户插入或拔出键盘、鼠标、手柄等外设时应用会立即收到通知// 定义监听回调letlistener:CallbackinputDevice.DeviceListener(data){if(data.typeadd){console.log(设备插入: deviceIddata.deviceId);// 获取新设备信息letinfoinputDevice.getDeviceInfoSync(data.deviceId);console.log( 新设备名称: info.name);// 可以在此更新UI如显示键盘已连接提示}else{console.log(设备移除: deviceIddata.deviceId);}};// 注册监听inputDevice.on(change,listener);// 不再需要时注销inputDevice.off(change,listener);重要off()必须传入与on()注册时相同的回调函数引用。如果传入匿名函数或不同的引用注销将无效导致内存泄漏。在 Demo 中监听注册后所有事件都会记录在日志列表中startDeviceListener():void{if(this.isListening)return;this.changeListener(data:inputDevice.DeviceListener){lettypeStrdata.typeadd?设备插入:设备移除;letcolordata.typeadd?#10B981:#EF4444;this.addLog(typeStr,deviceIddata.deviceId.toString(),color);this.refreshDevices();// 自动更新设备列表};inputDevice.on(change,this.changeListener);this.isListeningtrue;}四、键盘类型检测getKeyboardTypeSync()可以区分不同类型的键盘设备。这对于优化输入体验很有价值——例如在检测到全字母键盘后显示快捷键或在数字键盘下调整 UI 布局try{letkt:inputDevice.KeyboardTypeinputDevice.getKeyboardTypeSync(deviceId);if(ktinputDevice.KeyboardType.ALPHABETIC_KEYBOARD){console.log(全键盘 — 可显示快捷键);}elseif(ktinputDevice.KeyboardType.DIGITAL_KEYBOARD){console.log(数字键盘 — 仅数字输入);}elseif(ktinputDevice.KeyboardType.HANDWRITING_PEN){console.log(手写笔 — 开启手写模式);}elseif(ktinputDevice.KeyboardType.NONE){console.log(非键盘设备);}}catch(e){// 某些设备不支持键盘类型查询如鼠标、触控板会抛异常console.log(该设备无键盘类型);}五、空闲计时器getIntervalSinceLastInput()返回自用户最后一次操作触摸屏幕、按键、移动鼠标等以来经过的毫秒数。这是一个很有用的 API省电模式空闲超过 60 秒降低帧率或暂停动画自动保存用户停止输入 5 秒后触发安全锁屏空闲超过 5 分钟触发认证活跃度统计记录用户操作频率inputDevice.getIntervalSinceLastInput().then((ms:number){if(ms1000){console.log(用户刚刚操作过 (msms));}elseif(ms60000){console.log(距上次输入: (ms/1000).toFixed(1) 秒);}else{console.log(空闲: (ms/60000).toFixed(1) 分钟);}}).catch((err:Error){console.error(获取空闲时间失败);});六、实战 Demo输入设备实验室页面结构Demo 页面InputDevicePage.ets整合了上述全部功能输入设备实验室 ├── 状态栏 — 实时操作反馈 ├── 设备概况 │ ├── 已连接设备数 距上次输入时长 │ ├── 刷新设备列表 按钮 │ ├── 刷新空闲时间 按钮 │ └── 热插拔监听 / 停止监听 按钮 ├── 设备详情卡片列表 │ ├── 设备名称 ID │ ├── 输入源类型多标签 │ ├── 来源数 / 总线 / 键盘类型 │ └── Product / Vendor / Version ├── 热插拔事件日志 — 最近15条事件 └── 核心 API 参考 — 10 个关键 API4 个交互点刷新设备列表— 调用getDeviceList()getDeviceInfoSync()枚举所有已连接输入设备展示名称、类型、厂商信息刷新空闲时间— 调用getIntervalSinceLastInput()显示距离上次用户操作的精确时长热插拔监听— 通过on(change)注册设备插拔事件所有变更实时反映在设备列表和事件日志中键盘类型识别— 对每个设备调用getKeyboardTypeSync()区分全键盘、数字键盘、手写笔、遥控器等核心代码位置完整代码在dev/entry/src/main/ets/pages/InputDevicePage.ets约 320 行路由已注册为pages/InputDevicePage。七、API 总结表API返回值说明getDeviceList()PromiseArraynumber获取所有已连接设备IDgetDeviceInfoSync(id)InputDeviceData同步获取设备详细信息getKeyboardTypeSync(id)KeyboardType获取设备键盘类型getIntervalSinceLastInput()Promisenumber获取距上次输入的毫秒数on(change, cb)void注册热插拔事件监听off(change, cb)void注销热插拔事件监听八、与连接管理模块的对比上一篇文章介绍的ohos.net.connection与本文的inputDevice在 API 设计上有不少相似之处维度net.connectioninputDevice枚举getAllNetsSync()getDeviceList()异步详情getNetCapabilitiesSync()getDeviceInfoSync()事件NetConnection.on(netAvailable)等 6 种事件inputDevice.on(change)两种事件注册netConnection.register(callback)无需注册直接on()注销netConnection.unregister(callback)inputDevice.off(change, callback)权限ohos.permission.GET_NETWORK_INFO无需权限inputDevice的 API 更加轻量——没有register()/unregister()生命周期管理直接通过on()/off()注册和注销事件监听保持了极简的使用体验。九、实用场景1. 外接键盘时显示快捷键提示letdeviceIdsawaitinputDevice.getDeviceList();for(leti0;ideviceIds.length;i){try{letktinputDevice.getKeyboardTypeSync(deviceIds[i]);if(ktinputDevice.KeyboardType.ALPHABETIC_KEYBOARD){// 显示 CtrlS 保存、CtrlZ 撤销等快捷键提示this.showHotkeyBar();break;}}catch(e){/* 非键盘设备跳过 */}}2. 游戏场景检测手柄连接// 监听设备插拔inputDevice.on(change,(data){if(data.typeadd){letinfoinputDevice.getDeviceInfoSync(data.deviceId);if(info.sources.indexOf(joystick)0){this.onGamepadConnected(info.name);// 切换到手柄操作模式}}else{if(this.activeGamepadIddata.deviceId){this.onGamepadDisconnected();// 切换到触屏模式}}});3. 空闲检测触发自动锁屏setInterval((){inputDevice.getIntervalSinceLastInput().then((ms){if(ms5*60*1000){// 5分钟无操作this.lockScreen();// 触发安全锁屏}});},30000);// 每30秒检查一次十、总结ohos.multimodalInput.inputDevice为 HarmonyOS NEXT 应用提供了完整的输入外设感知能力设备枚举—getDeviceList()getDeviceInfoSync()发现所有已连接输入设备6种输入源类型— 键盘、鼠标、触控板、触摸屏、摇杆、轨迹球5种键盘类型— 无键盘、未知、全字母键盘、数字键盘、手写笔、遥控器热插拔监听—on(change)实时感知设备插入与拔出空闲计时器—getIntervalSinceLastInput()精确到毫秒的用户空闲检测零权限门槛— 无需申请任何系统权限这个模块虽然小巧但为键盘快捷键适配、手柄游戏支持、手写笔优化、省电模式等场景提供了关键的底层能力。结合上一篇文章的net.connection网络管理你已经掌握了构建设备感知型应用的两种核心基础设施。