多模输入开发指导
场景介绍
多模输入使用HarmonyOS的UI组件能够响应多种输入事件，事件来源于用户的按键、点击、触屏、语音等，并且提供创建事件能力和获取输入设备信息能力。
接口说明
多模输入提供了多模事件基类（MultimodalEvent），以及其派生的操作事件类（ManipulationEvent）、按键事件类（KeyEvent）、语音事件类（SpeechEvent）等，另外提供创建事件类（EventCreator）和获取输入设备信息类（InputDevice）。
图1 多模输入事件类
MultimodalEvent是所有事件的基类，该类中定义了一系列高级事件类型，这些事件类型通常是对某种行为或意图的抽象。
| 功能分类 | 接口名 | 描述 | | -------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | | 设备信息相关 | getDeviceId() | 获取输入设备所在的承载设备id，如当同时有两个鼠标连接到一个机器上，该机器为这两个鼠标的承载设备。 | | getInputDeviceId() | 获取产生当前事件的输入设备id，该id是该输入设备的唯一标识，如两个鼠标同时输入时，它们会分别产生输入事件，且从事件中获取到的deviceid是不同的，开发者可以将此id用来区分实际的输入设备源。 | | | getSourceDevice() | 获取产生当前事件的输入设备类型。 | | | 时间 | getOccurredTime() | 获取产生当前事件的时间。 | | 事件 | getUuid() | 获取事件的UUID。 | | isSameEvent(UUID id) | 判断当前事件与传入id的事件是否为同一事件。 | |
CompositeEvent处理常用设备对应的事件，当前只有MouseEvent事件继承该类。
SpeechEvent处理语音事件，开发者可以通过该类获取语音识别结果。
| 功能分类 | 接口名 | 描述 | | ------------------- | ------------------------------------------------------------ | -------------------------------------- | | 构造函数 | Optional
createEvent(long occurTime, int action, String value) | SpeechEvent创建函数。 | | 获取语音事件参数值 | getAction() | 获取当前动作，如打开、关闭、命中热词。 | | getScene() | 获取当前动作的场景。 | | | getActionProperty() | 获取动作所携带的属性值。 | | | getMatchMode() | 获取语音识别的模式。 | | ManipulationEvent操作类事件是对手指触摸等事件的抽象。该事件会持有事件发生的位置信息和发生的阶段等信息。通常情况下，该事件主要是作为操作回调接口的入参，开发者通过回调接口捕获及处理事件。回调接口分为操作开始、操作过程和操作结束。例如对于一次手指触控，手指接触屏幕是操作开始，手指在屏幕上移动是操作过程，手指抬起是操作结束。
| 功能分类 | 接口名 | 描述 | | --------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------- | | 手指信息 | getPointerCount() | 获取一次事件中触控或轨迹追踪的指针数量。 | | getPointerId(int index) | 获取一次事件中，指针的唯一标识Id。 | | | setScreenOffset(float offsetX, float offsetY) | 设置相对屏幕坐标原点的偏移位置。 | | | getPointerPosition(int index) | 获取一次事件中触控或轨迹追踪的某个指针相对于偏移位置的坐标。 | | | getPointerScreenPosition(int index) | 获取一次事件中触控或轨迹追踪的某个指针相对屏幕坐标原点的坐标。 | | | getRadius(int index) | 返回指定index手指与屏幕接触的半径值。 | | | getForce(int index) | 获取指定index手指触控的压力值。 | | | 时间 | getStartTime() | 获取操作开始时间。 | | 阶段 | getPhase() | 获取事件所属阶段。 |
KeyEvent对所有按键类事件的定义，该类继承MultimodalEvent类，并对按键类事件做了专属的keycode定义以及方法封装。
| 功能分类 | 接口名 | 描述 | | --------------- | --------------------------------------- | ------------------------------- | | KeyCode | getKeyCode() | 获取当前按键类事件的keycode值。 | | getMaxKeyCode() | 获取当前定义的按键事件的最大keycode值。 | | | 按键按下状态 | getKeyDownDuration() | 获取当前按键被按下的持续时长。 | | isKeyDown() | 获取当前按键事件是否是按下状态。 | |
TouchEvent处理手指触控相关事件。
| 功能分类 | 接口名 | 描述 | | ---------- | ------------------------ | ------------------ | | 触控行为 | getAction() | 获取当前触摸行为。 | | getIndex() | 获取当前触摸行为的指针。 | |
KeyBoardEvent处理键盘类设备的事件。
| 功能分类 | 接口名 | 描述 | | ------------------------------------------------------------ | ------------------------------------------------- | ----------------------------------------------- | | 输入法编辑器 | enableIme() | 启动输入法编辑器。 | | disableIme() | 关闭输入法编辑器。 | | | isHandledByIme() | 判断输入法编辑器是否在使用。 | | | NoncharacterKey行为 | isNoncharacterKeyPressed(int keycode) | 判定输入的单个NoncharacterKey是否处于按下状态。 | | isNoncharacterKeyPressed(int keycode1, int keycode2) | 判定输入的两个NoncharacterKey是否都处于按下状态。 | | | isNoncharacterKeyPressed(int keycode1, int keycode2, int keycode3) | 判定输入的三个NoncharacterKey是否都处于按下状态。 | | | 按键Unicode码 | getUnicode() | 获取按键对应的Unicode码。 |
说明
NoncharacterKey为除了文本可见字符（A-Z，0-9，空格，逗号，句号等）以外的按键码，例如：Ctrl，Alt，Shift等。
MouseEvent处理鼠标的事件。
| 功能分类 | 接口名 | 描述 | | --------------------------------------------- | ---------------------------------- | ---------------------------- | | 鼠标行为 | getAction() | 获取鼠标设备产生事件的行为。 | | 鼠标按键 | getActionButton() | 获取状态发生变化的鼠标按键。 | | getPressedButtons() | 获取所有按下状态的鼠标按键。 | | | 鼠标指针/位置 | getCursor() | 获取鼠标指针的位置。 | | getCursorDelta(int axis) | 获取鼠标指针位置相对上次的变化值。 | | | setCursorOffset(float offsetX, float offsetY) | 设置相对屏幕的偏移位置信息。 | | | 鼠标滚轮 | getScrollingDelta(int axis) | 获取滚轮的滚动值。 |
MmiPoint处理在指定坐标系中的坐标。
| 功能分类 | 接口名 | 描述 | | -------------------------------------- | --------------------------------------- | -------------------------------------- | | 构造函数 | MmiPoint(float px, float py) | 创建一个只包含x和y坐标的MmiPoint对象。 | | MmiPoint(float px, float py, float pz) | 创建一个包含x，y和z坐标的MmiPoint对象。 | | | 坐标值 | getX() | 获取x坐标值。 | | getY() | 获取y坐标值。 | | | getZ() | 获取z坐标值。 | | | toString() | 返回包含x、y、z坐标值信息的字符串 | |
EventCreator提供创建事件的方法，当前仅提供创建KeyEvent事件的能力。
| 功能分类 | 接口名 | 描述 | | -------- | ------------------------------------------------------------ | --------------------------------------- | | 创建事件 | Optional
createKeyEvent(int action, int keyCode) | 根据指定的action和keycode创建KeyEvent。 | InputDevice提供获取承载设备上输入设备信息的方法，当前支持获取所有输入设备的ID。
| 功能分类 | 接口名 | 描述 | | -------- | --------------------- | ------------------------------------------------------------ | | 设备ID | getAllInputDeviceID() | 获取承载设备上所有输入设备的ID，例如承载设备为智慧屏，其中有键盘、鼠标和遥控器作为智慧屏的输入设备，该方法用于获取键盘、鼠标和遥控器的ID。 |
开发步骤
处理按钮事件
参考HarmonyOS的Component的API创建KeyEventListener。
重写实现KeyEventListener类中的onKeyEvent(Component component, KeyEvent event)方法。
开发者根据需要实现按键被按下后的处理逻辑。
private Component.KeyEventListener onKeyEvent = new Component.KeyEventListener() { @Override public boolean onKeyEvent(Component component, KeyEvent keyEvent) { if (keyEvent.isKeyDown()) { ... // 检测到按键被按下，开发者根据需求实现 } int keycode = keyEvent.getKeyCode(); switch (keycode) { case KeyEvent.KEY_DPAD_CENTER: ... // 检测到KEY_DPAD_CENTER被按下，开发者根据需求实现 break; case KeyEvent.KEY_DPAD_LEFT: ... // 检测到KEY_DPAD_LEFT被按下，开发者根据需求实现 break; case KeyEvent.KEY_DPAD_UP: ... // 检测到KEY_DPAD_UP被按下，开发者根据需求实现 break; case KeyEvent.KEY_DPAD_RIGHT: ... // 检测到KEY_DPAD_RIGHT被按下，开发者根据需求实现 break; case KeyEvent.KEY_DPAD_DOWN: ... // 检测到KEY_DPAD_DOWN被按下，开发者根据需求实现 break; default: break; } ... }};
处理语音事件
使用多模输入的语音事件实现“可见即可说”的效果，简易开发样例参考可见即可说开发指导。