大网数据广告活动
OpenHarmony 设备与应用开发

全局基础输入事件监听

· 52CE 我爱测

此类为抽象类,开发者无法自行创建实例。系统会在触发输入事件监听器时自动创建实例并传递回调函数。

全局基础输入事件监听

监听基础输入事件,在UIContext进行事件分发前统一拦截和过滤输入事件,使用示例请参考addLocalInputEventMonitor。

起始版本: 26.0.0

InputEventMonitor

输入事件监听器标识对象。

此对象由系统创建并返回,作为监听器的唯一标识。

说明:

  • 对象为空对象,不包含任何可访问的成员。
  • 开发者无法主动构造此对象,只能通过addLocalInputEventMonitor接口注册获取。
  • 用于后续解除注册时验证身份。

起始版本: 26.0.0

原子化服务API: 从API版本26.0.0开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

模型约束: 此接口仅可在Stage模型下使用。

InputEventListener

type InputEventListener = (event: RawInputEventWrapper) => InputEventInterceptResult

输入事件监听器回调函数类型。

说明:

  • RawInputEventWrapper是抽象类,开发者无法使用new运算符创建实例。
  • 系统会在事件触发时自动创建实例并通过此参数传递给回调函数。
  • 当前回调参数event仅会封装以下原始输入事件类型:MouseEvent、TouchEvent、KeyEvent。开发者可通过asMouseEvent、asTouchEvent、asKeyEvent获取对应事件对象。
  • 请勿在回调中执行耗时操作(如复杂计算或网络请求),否则可能导致应用卡顿。
  • 监听器在UI线程中同步执行会直接阻塞事件处理流程。建议只进行简单的判断和计算。

起始版本: 26.0.0

原子化服务API: 从API版本26.0.0开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

模型约束: 此接口仅可在Stage模型下使用。

参数:

参数名 类型 必填 说明
event RawInputEventWrapper 是 输入事件包装器,系统自动创建和传递,开发者无需手动创建。

返回值:

类型 说明
InputEventInterceptResult 事件拦截结果。

InputEventInterceptResult

输入事件拦截结果接口,用于监听器回调InputEventListener返回是否拦截的决策。

起始版本: 26.0.0

原子化服务API: 从API版本26.0.0开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

模型约束: 此接口仅可在Stage模型下使用。

名称 类型 只读 可选 说明
action InputEventInterceptAction 否 否 输入事件拦截动作。
CONTINUE:允许事件继续传递到UI框架。
BLOCK:阻止事件传递到UI框架。

RawInputEventWrapper

原始输入事件包装器类。

提供统一的接口来访问不同类型的输入事件,确保类型安全和向后兼容性。

此类封装了原始的MouseEvent、TouchEvent或KeyEvent对象,并通过类型安全的方法访问。

此类为抽象类,开发者无法自行创建实例。系统会在触发输入事件监听器时自动创建实例并传递回调函数。

说明:

由于监听器在事件派发给具体组件之前执行,事件中的一些字段将无法提供有效值:如触发对象target、相对于组件的坐标(x,y)、getCurrentLocalPosition和stopPropagation方法、TouchEvent的preventDefault和getHistoricalPoints方法以及KeyEvent的metaKey属性和getModifierKeyState方法。

示例:

const listener: InputEventListener = (wrapper: RawInputEventWrapper) => {
  // 使用类型判断 + 获取事件对象
  if (wrapper.isMouseEvent()) {
    const mouseEvent = wrapper.asMouseEvent()!;
    console.info(`Mouse: (${mouseEvent.windowX}, ${mouseEvent.windowY})`);
    return { action: InputEventInterceptAction.CONTINUE };
  }
  if (wrapper.isTouchEvent()) {
    const touchEvent = wrapper.asTouchEvent()!;
    console.info(`Touch: ${touchEvent.touches.length} points`);
    return { action: InputEventInterceptAction.CONTINUE };
  }
  if (wrapper.isKeyEvent()) {
    const keyEvent = wrapper.asKeyEvent()!;
    console.info(`Key: ${keyEvent.keyText}`);
    return { action: InputEventInterceptAction.CONTINUE };
  }
  return { action: InputEventInterceptAction.CONTINUE };
};

isMouseEvent

isMouseEvent(): boolean

判断是否为鼠标事件。

起始版本: 26.0.0

原子化服务API: 从API版本26.0.0开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

模型约束: 此接口仅可在Stage模型下使用。

返回值:

类型 说明
boolean 判断是否为鼠标事件,如果是鼠标事件则返回true,否则返回false。

isTouchEvent

isTouchEvent(): boolean

判断是否为触摸事件。

起始版本: 26.0.0

原子化服务API: 从API版本26.0.0开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

模型约束: 此接口仅可在Stage模型下使用。

返回值:

类型 说明
boolean 判断是否为触摸事件,如果是触摸事件则返回true,否则返回false。

isKeyEvent

isKeyEvent(): boolean

判断是否为按键事件。

起始版本: 26.0.0

原子化服务API: 从API版本26.0.0开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

模型约束: 此接口仅可在Stage模型下使用。

返回值:

类型 说明
boolean 判断是否为按键事件,如果是按键事件则返回true,否则返回false。

asMouseEvent

asMouseEvent(): MouseEvent | null

获取鼠标事件。

起始版本: 26.0.0

原子化服务API: 从API版本26.0.0开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

模型约束: 此接口仅可在Stage模型下使用。

返回值:

类型 说明
MouseEvent | null 获取鼠标事件,如果是鼠标事件则返回事件对象,否则返回null。

asTouchEvent

asTouchEvent(): TouchEvent | null

获取触摸事件。

起始版本: 26.0.0

原子化服务API: 从API版本26.0.0开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

模型约束: 此接口仅可在Stage模型下使用。

返回值:

类型 说明
TouchEvent | null 获取触摸事件,如果是触摸事件则返回事件对象,否则返回null。

asKeyEvent

asKeyEvent(): KeyEvent | null

获取按键事件。

起始版本: 26.0.0

原子化服务API: 从API版本26.0.0开始,该接口支持在原子化服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

模型约束: 此接口仅可在Stage模型下使用。

返回值:

类型 说明
KeyEvent | null 获取按键事件,如果是按键事件则返回事件对象,否则返回null。

本文来自 OpenHarmony 文档贡献者,按 CC BY 4.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
OpenHarmony 文档贡献者
适用范围
master 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
CC BY 4.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。