输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
文档管理中心
全部文档版本说明工具设计指南与API参考开发与测试上架分发与运营问题处理与运维最佳实践行业解决方案
指南与API参考
指南
API
您当前正在浏览新版开发者文档中心，目录分类和层级有所调整。点击左侧当前文档分类名称前的“☰”图标，可切换文档分类。 了解新版目录
指南与API参考指南应用框架ArkUI（方舟UI框架）窗口管理其他开发场景使用WindowManager管理多模输入事件 (C/C++)

使用WindowManager管理多模输入事件 (C/C++)

更新时间: 2026-09-09 06:54
复制页面
本文导读
展开章节

场景介绍

WindowManager提供应用窗口的管理能力，可以用于管理多模输入事件。

当前支持使用WindowManager进行多模输入事件的过滤，还可以将多模触摸事件注入目标窗口，具体开发步骤可见下文。

过滤多模输入事件

使用WindowManager模块提供的能力去拦截按键事件，让按键事件不往应用内部组件分发。

在CMake脚本中链接动态库

收起
自动换行
深色代码主题
复制
  1. target_link_libraries(entry PUBLIC libnative_window_manager.so libohinput.so)

接口使用说明

展开
接口名 描述
OH_NativeWindowManager_RegisterKeyEventFilter(int32_t windowId, OH_NativeWindowManager_KeyEventFilter keyEventFilter) 为指定的窗口注册过滤回调函数keyEventFilter。
OH_NativeWindowManager_UnregisterKeyEventFilter(int32_t windowId) 取消指定窗口上的过滤回调函数。
  • 应用窗口创建后，使用窗口ID绑定按键事件过滤函数。
  • 应用窗口需要收到按键事件时，才触发按键事件的拦截。
  • 当回调函数返回true表示拦截，false表示不拦截。
  • 同一个窗口ID注册的回调函数只允许一个，最后注册的回调函数会覆盖之前注册过的回调函数。如需过滤多个按键的组合场景，建议在一个回调函数里面处理。

示例代码

以下示例代码中介绍了如何注册过滤函数和取消过滤函数，以过滤ESC退出按键和数字按键为例。

收起
自动换行
深色代码主题
复制
  1. #include "napi/native_api.h"
  2. #include "window_manager/oh_window_comm.h"
  3. #include "window_manager/oh_window_event_filter.h"
  4. #include "multimodalinput/oh_input_manager.h"
  5. #include "multimodalinput/oh_key_code.h"
  6. 

  7. // 设置过滤函数
  8. static bool filterFunc(Input_KeyEvent *event)
  9. {
  10.     auto keyCode = OH_Input_GetKeyEventKeyCode(event);
  11.     auto action = OH_Input_GetKeyEventAction(event);
  12.     
  13.     // 过滤escape和数字键的按下
  14.     return (keyCode >= Input_KeyCode::KEYCODE_0 && keyCode <= Input_KeyCode::KEYCODE_9
  15.          && action == Input_KeyEventAction::KEY_ACTION_DOWN) || (keyCode == Input_KeyCode::KEYCODE_ESCAPE);
  16. }
  17. 

  18. static napi_value registerFilter(napi_env env, napi_callback_info info)
  19. {
  20.     size_t argc = 1;
  21.     napi_value args[1] = {nullptr};
  22.     napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
  23.     
  24.     int32_t windowId;
  25.     napi_get_value_int32(env, args[0], &windowId);
  26.     
  27.     // 向windowId对应的窗口注册filterFunc的过滤函数
  28.     auto res = OH_NativeWindowManager_RegisterKeyEventFilter(windowId, filterFunc);
  29.     
  30.     napi_value errCode;
  31.     napi_create_int32(env, res, &errCode);
  32.     return errCode;
  33. }
  34. 

  35. static napi_value clearFilter(napi_env env, napi_callback_info info)
  36. {
  37.     size_t argc = 1;
  38.     napi_value args[1] = {nullptr};
  39.     napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
  40. 

  41.     int32_t windowId;
  42.     napi_get_value_int32(env, args[0], &windowId);
  43. 

  44.     auto res = OH_NativeWindowManager_UnregisterKeyEventFilter(windowId);
  45.     napi_value errCode;
  46.     napi_create_int32(env, res, &errCode);
  47.     return errCode;
  48. }
  49. 

  50. EXTERN_C_START
  51. static napi_value Init(napi_env env, napi_value exports)
  52. {
  53.     napi_property_descriptor desc[] = {
  54.         {"registerFilter", nullptr, registerFilter, nullptr, nullptr, nullptr, napi_default, nullptr},
  55.         {"clearFilter", nullptr, clearFilter, nullptr, nullptr, nullptr, napi_default, nullptr}};
  56.     napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
  57.     return exports;
  58. }
  59. EXTERN_C_END
napi_init.cpp

将多模触摸事件注入给目标窗口

使用WindowManager模块提供的能力为指定窗口注入触摸事件，仅支持同进程窗口。此操作不会触发窗口焦点、层级变化或拖拽，事件会直接发送给ArkUI。

在CMake脚本中链接动态库

收起
自动换行
深色代码主题
复制
  1. target_link_libraries(entry PUBLIC libnative_window_manager.so libohinput.so)

接口使用说明

展开
接口名 描述
OH_WindowManager_InjectTouchEvent(int32_t windowId, Input_TouchEvent* touchEvent, int32_t windowX, int32_t windowY) 为指定的窗口注入触摸事件。

  • 构造事件参数，向目标窗口ID注入事件。

  • 仅支持注入同进程窗口。注入不会触发窗口焦点、层级变化或拖拽，事件直接发送给ArkUI。

  • 接口需要在指定窗口加载UI后调用。

  • 完成窗口和多模触摸事件校验，确保事件参数正确，再将事件发送给ArkUI。具体参数说明如下：

    展开
    参数名 描述
    windowId 目标窗口ID，仅支持同进程的窗口，否则返回错误码1300002。窗口需完成UI加载，否则返回错误码1300003。
    touchEvent 多模触摸事件，具体可见Input_TouchEvent，事件定义在oh_input_manager.h中。调用OH_Input_CreateTouchEvent接口创建touchEvent对象，使用完后调用OH_Input_DestroyTouchEvent接口销毁该对象。具体参数说明见下表。
    windowX 注入事件相对于注入窗口的落点横坐标。参数应为大于等于0的整数，否则返回错误码1300003。
    windowY 注入事件相对于注入窗口的落点纵坐标。参数应为大于等于0的整数，否则返回错误码1300003。

    其中，touchEvent多模触摸事件具体参数说明如下：

    展开
    参数名 方法 描述
    action OH_Input_SetTouchEventAction

    表示事件行为，默认值为0。

    当前只支持0-3的行为，分别表示为：

    - 0：cancel，表示取消事件。

    - 1：down，表示按下事件。

    - 2：move，表示移动事件。

    - 3：up，表示抬起事件。

    - 其他行为会返回错误码1300003。
    id OH_Input_SetTouchEventFingerId

    表示手指ID，默认值为0。

    应为大于等于0的整数，否则返回错误码1300003。
    displayX OH_Input_SetTouchEventDisplayX

    表示事件落点相对于屏幕的横坐标，默认值为0。

    参数应为非负整数，否则返回错误码1300003。建议与windowX保持对应关系，即使不一致也不会返回错误码，仅校验入参合法范围。转换方法推荐使用getWindowProperties()方法获取windowRect属性，通过displayX减去windowRect中窗口左上角横坐标计算对应的windowX。
    displayY OH_Input_SetTouchEventDisplayY

    表示事件落点相对于屏幕的纵坐标，默认值为0。

    参数应为非负整数，否则返回错误码1300003。建议与windowY保持对应关系，即使不一致也不会返回错误码，仅校验入参合法范围。转换方法推荐使用getWindowProperties()方法获取windowRect属性，通过displayY减去windowRect中窗口左上角纵坐标计算对应的windowY。
    actionTime OH_Input_SetTouchEventActionTime 表示时间戳，默认值为-1。参数应为非负整数，否则返回错误码1300003。
    windowId OH_Input_SetTouchEventWindowId 表示事件注入窗口ID，默认值为-1。若参数不为默认值且不等于OH_WindowManager_InjectTouchEvent接口参数windowId，将校验传入参数错误。
    displayId OH_Input_SetTouchEventDisplayId 表示事件注入屏幕ID，默认值为-1。无限制，但是应该尽量保证与OH_WindowManager_InjectTouchEvent接口参数windowId有相互对应关系，推荐使用getWindowProperties()方法获取displayId属性。

示例代码

以下示例代码介绍了如何将多模触摸事件注入目标窗口，以单次事件注入为例。

收起
自动换行
深色代码主题
复制
  1. #include "napi/native_api.h"
  2. #include "window_manager/oh_window.h"
  3. #include "multimodalinput/oh_input_manager.h"
  4. 

  5. const int32_t ARGS_TWO = 2;
  6. const int32_t ARGS_THREE = 3;
  7. const int32_t ARGS_FOUR = 4;
  8. const int32_t ARGS_FIVE = 5;
  9. const int32_t ARGS_SIX = 6;
  10. const int32_t ARGS_SEVEN = 7;
  11. const int32_t ARGS_EIGHT = 8;
  12. const int32_t ARGS_NINE = 9;
  13. const int32_t ARGS_TEN = 10;
  14. 

  15. static napi_value injectEvent(napi_env env, napi_callback_info info)
  16. {
  17.     size_t argc = ARGS_TEN;
  18.     napi_value args[ARGS_TEN] = {nullptr};
  19.     napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
  20. 

  21.     int32_t windowId;
  22.     napi_get_value_int32(env, args[0], &windowId);
  23. 

  24.     int32_t displayId;
  25.     napi_get_value_int32(env, args[1], &displayId);
  26. 

  27.     int32_t windowX;
  28.     napi_get_value_int32(env, args[ARGS_TWO], &windowX);
  29. 

  30.     int32_t windowY;
  31.     napi_get_value_int32(env, args[ARGS_THREE], &windowY);
  32. 

  33.     int32_t action;
  34.     napi_get_value_int32(env, args[ARGS_FOUR], &action);
  35. 

  36.     int32_t fingerId;
  37.     napi_get_value_int32(env, args[ARGS_FIVE], &fingerId);
  38. 

  39.     int32_t displayX;
  40.     napi_get_value_int32(env, args[ARGS_SIX], &displayX);
  41. 

  42.     int32_t displayY;
  43.     napi_get_value_int32(env, args[ARGS_SEVEN], &displayY);
  44. 

  45.     int32_t actionTime;
  46.     napi_get_value_int32(env, args[ARGS_EIGHT], &actionTime);
  47. 

  48.     int32_t TE_WindowId;
  49.     napi_get_value_int32(env, args[ARGS_NINE], &TE_WindowId);
  50.     
  51.     // 构造多模事件touchEvent
  52.     Input_TouchEvent* touchEvent = OH_Input_CreateTouchEvent();
  53.     OH_Input_SetTouchEventAction(touchEvent, action);
  54.     OH_Input_SetTouchEventFingerId(touchEvent, fingerId);
  55.     OH_Input_SetTouchEventDisplayX(touchEvent, displayX);
  56.     OH_Input_SetTouchEventDisplayY(touchEvent, displayY);
  57.     OH_Input_SetTouchEventActionTime(touchEvent, actionTime);
  58.     OH_Input_SetTouchEventWindowId(touchEvent, TE_WindowId);
  59.     OH_Input_SetTouchEventDisplayId(touchEvent, displayId);
  60. 

  61.     // 向windowId对应的窗口注入多模触摸事件
  62.     auto res = OH_WindowManager_InjectTouchEvent(windowId, touchEvent, windowX, windowY);
  63. 

  64.     // 使用完touchEvent后销毁对象
  65.     OH_Input_DestroyTouchEvent(&touchEvent);
  66.     
  67.     napi_value errCode;
  68.     napi_create_int32(env, res, &errCode);
  69.     return errCode;
  70. }
  71. 

  72. EXTERN_C_START
  73. static napi_value Init(napi_env env, napi_value exports)
  74. {
  75.     napi_property_descriptor desc[] = {
  76.         {"injectEvent", nullptr, injectEvent, nullptr, nullptr, nullptr, napi_default, nullptr}};
  77.     napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
  78.     return exports;
  79. }
  80. EXTERN_C_END
napi_init.cpp
控制窗口外观 (ArkTS)
应用启动页的配置与使用
简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明