鸿蒙OS 多模输入开发指导

场景介绍

多模输入使 HarmonyOS 的 UI 控件能够响应多种输入事件，事件来源于用户的按键、点击、触屏、语音等。例如用户希望通过语音操作UI控件，那么开发者可以通过多模输入在智慧屏产品上提供的语音事件达到“可见即可说”的效果。

接口说明

多模输入的接口设计是基于多模事件基类（MultimodalEvent），派生出操作事件类（ManipulationEvent）、按键事件类（KeyEvent）、语音事件（SpeechEvent）等，详细见[图1]。

图1 多模输入事件类的派生关系

• MultimodalEvent 是所有事件的基类，该类中定义了一系列高级事件类型，这些事件类型通常是对某种行为或意图的抽象。

功能分类	接口名	描述
设备信息相关	getDeviceId()	获取输入设备所在的承载设备 id，如当同时有两个鼠标连接到一个机器上，该机器为这两个鼠标的承载设备。
getInputDeviceId()	获取产生当前事件的输入设备 id，该 id 是该输入设备的唯一标识，如两个鼠标同时输入时，它们会分别产生输入事件，且从事件中获取到的 deviceid 是不同的，开发者可以将此 id 用来区分实际的输入设备源。
getSourceDevice()	获取产生当前事件的输入设备类型。
时间	getOccurredTime()	获取产生当前事件的时间。
事件	getUuid()	获取事件的UUID。
isSameEvent(UUID id)	判断当前事件与传入 id 的事件是否为同一事件。

• CompositeEvent 处理常用设备对应的事件，目前暂时只有 MouseEvent 事件继承该类。

• RotationEvent 处理由旋转器件产生的事件，比如智能穿戴上的数字表冠。

功能分类	接口名	描述
旋转器信息	getRotationValue()	获取旋转器件旋转产生的值。

• SpeechEvent 处理语音事件，开发者可以通过该类获取语音识别结果。

功能分类	接口名	描述
构造函数	public static Optional<SpeechEvent> createEvent(long occurTime, int action, String value)	SpeechEvent 创建函数。
获取语音事件参数值	public int getAction()	获取当前动作的类型，如打开、关闭、命中热词。
public int getScene()	获取当前动作时的场景。
public String getActionProperty()	获取动作所携带的属性值。
public int 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处理在指定给定的坐标系中的 x,y 和 z 坐标。

功能分类	接口名	描述
构造函数	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坐标值信息的字符串

开发步骤

处理按钮事件

1. 参考 HarmonyOS 的 Component 的 API 创建 KeyEventListener；

1. 重写实现 KeyEventListener 类中的onKeyEvent(Component component, KeyEvent event)方法；

1. 开发者根据自身需求处理存在按键被按下以及 KEY_DPAD_CENTER、KEY_DPAD_LEFT 等按键被按下后的具体实现。

   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;
           }
           ... 
       }
   };

处理语音事件

使用多模输入的语音事件实现“可见即可说”的效果简易开发样例参考可见即可说开发指导。