输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
管理中心
全部文档版本说明工具设计指南与API参考开发与测试上架分发与运营问题处理与运维最佳实践行业解决方案
指南与API参考
指南
API
您当前正在浏览新版开发者文档中心，目录分类和层级有所调整。点击左侧当前文档分类名称前的“☰”图标，可切换文档分类。 了解新版目录
指南与API参考指南系统硬件Multimodal Awareness Kit（多模态融合感知服务）获取用户动作开发指导

获取用户动作开发指导

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

场景介绍

当应用需要获取用户动作时，可以调用motion模块，例如判断用户当前是用左手还是右手操作设备屏幕。

详细的接口介绍请参考@ohos.multimodalAwareness.motion (动作感知能力)。

从API version 15开始，支持获取操作手状态。从API version 20开始，支持获取握持手状态。

获取操作手状态开发指导

接口说明

展开
接口名 描述
on(type:'operatingHandChanged',callback:Callback<OperatingHandStatus>):void; 订阅操作手感知，操作手结果通过callback返回。
off(type: 'operatingHandChanged', callback?: Callback<OperatingHandStatus>): void; 取消订阅操作手感知。
getRecentOperatingHandStatus(): OperatingHandStatus; 获取最新的操作手状态。

需要权限

使用motion模块获取用户操作手时，需要权限：ohos.permission.ACTIVITY_MOTION 或 ohos.permission.DETECT_GESTURE，具体申请方式请参考声明权限。

收起
自动换行
深色代码主题
复制
  1. "requestPermissions":[
  2.     {
  3.       "name" : "ohos.permission.ACTIVITY_MOTION",
  4.       // reason和usedScene按需填写
  5.       "reason" : "", // 用于应用上架校验
  6.       "usedScene" : {
  7.          "abilities" : [
  8.             "" // 使用权限的名称
  9.          ],
  10.          "when" : "" // 调用时机
  11.       },
  12.     },
  13.     {
  14.       "name" : "ohos.permission.DETECT_GESTURE"
  15.     }
  16.   ]

约束与限制

  • 此功能如果设备不支持，将返回801错误码。

  • 指关节操作不属于使用手操作场景。

  • 窗口旋转场景，多指同时操作场景不支持。

  • 能力有效范围：不包含距离屏幕边缘8mm内区域。

  • 结果上报条件：首次订阅或切换操作手后，连续点数次触发。

  • 触控响应说明：屏幕四周边缘8mm范围内不支持触控响应。

开发步骤

  1. 导入模块。

    收起
    自动换行
    深色代码主题
    复制
    1. import { motion } from '@kit.MultimodalAwarenessKit';
    2. import { BusinessError } from '@kit.BasicServicesKit';
    Index.ets

  2. 定义回调函数接收操作手结果

    收起
    自动换行
    深色代码主题
    复制
    1. let callback:Callback<motion.OperatingHandStatus> = (data:motion.OperatingHandStatus) => {
    2.   console.info('callback succeeded' + data);
    3. };
    Index.ets

  3. 订阅操作手感知

    收起
    自动换行
    深色代码主题
    复制
    1. try {
    2.   motion.on('operatingHandChanged', callback);
    3.   console.info('on succeeded');
    4.   // ...
    5. } catch (err) {
    6.   let error = err as BusinessError;
    7.   console.error('Failed on and err code is ' + error.code);
    8.   // ...
    9. }
    Index.ets

  4. 取消订阅操作手感知

    收起
    自动换行
    深色代码主题
    复制
    1. try {
    2.   motion.off('operatingHandChanged');
    3.   console.info('off succeeded');
    4.   // ...
    5. } catch (err) {
    6.   let error = err as BusinessError;
    7.   console.error('Failed off and err code is ' + error.code);
    8.   // ...
    9. }
    Index.ets

  5. 获取最新操作手状态

    收起
    自动换行
    深色代码主题
    复制
    1. try {
    2.   let data:motion.OperatingHandStatus = motion.getRecentOperatingHandStatus();
    3.   console.info('get succeeded' + data);
    4.   // ...
    5. } catch (err) {
    6.   let error = err as BusinessError;
    7.   console.error('Failed get and err code is ' + error.code);
    8.   // ...
    9. }
    Index.ets

获取握持手状态开发指导

接口说明

展开
接口名 描述
on(type:'holdingHandChanged',callback:Callback<HoldingHandStatus>): void; 订阅握持手感知，感知结果通过callback返回。
off(type: 'holdingHandChanged', callback?: Callback<HoldingHandStatus>): void; 取消订阅握持手感知。

需要权限

使用motion模块获取用户握持手时，需要权限： ohos.permission.DETECT_GESTURE，具体申请方式请参考声明权限。

收起
自动换行
深色代码主题
复制
  1. "requestPermissions":[
  2.     {
  3.       "name" : "ohos.permission.DETECT_GESTURE"
  4.     }
  5.   ]

约束与限制

  • 此功能当前支持部分机型，若设置菜单中存在“智感握姿”开关（可在“设置-系统”中查看），则表明该设备支持此功能，若无此开关，将返回801错误码。
  • 设备屏幕需处于亮屏且解锁状态。
  • 设备保护壳（若有）厚度不得超过3毫米。
  • 需以五指自然握持设备，同时掌心区域接触设备（或拇指外的四指及掌心区域接触）。
  • 握持时确保每根接触手指的接触面积尽可能大（理想情况下不低于30mm²）。
  • 佩戴手套会显著降低识别准确率。
  • 竖屏握持时，摄像头需朝上。
  • 支持横屏握持，但需要注意：应用横屏时竖屏握持即握持设备长边，应用竖屏时横屏握持即握持设备短边，均属异常姿态，无法保证识别成功。
  • 握持时屏幕需朝向握持人。
  • 握持时不得同时接触其他物体（如桌面、其他身体部位等）。
  • 未握持的识别依赖设备状态，设备非静止时无法保证识别成功。

开发步骤

  1. 导入模块。

    收起
    自动换行
    深色代码主题
    复制
    1. import { motion } from '@kit.MultimodalAwarenessKit';
    2. import { BusinessError } from '@kit.BasicServicesKit';
    Index.ets

  2. 定义回调函数接收握持手结果

    收起
    自动换行
    深色代码主题
    复制
    1. let callback:Callback<motion.HoldingHandStatus> = (data:motion.HoldingHandStatus) => {
    2.   console.info('callback succeeded' + data);
    3. };
    Index.ets

  3. 订阅握持手感知

    收起
    自动换行
    深色代码主题
    复制
    1. try {
    2.   motion.on('holdingHandChanged', callback);
    3.   console.info('on succeeded');
    4.   // ...
    5. } catch (err) {
    6.   let error = err as BusinessError;
    7.   console.error('Failed on and err code is ' + error.code);
    8.   // ...
    9. }
    Index.ets

  4. 取消订阅握持手感知

    收起
    自动换行
    深色代码主题
    复制
    1. try {
    2.   motion.off('holdingHandChanged');
    3.   console.info('off succeeded');
    4.   // ...
    5. } catch (err) {
    6.   let error = err as BusinessError;
    7.   console.error('Failed off and err code is ' + error.code);
    8.   // ...
    9. }
    Index.ets
Stationary开发指导
设备状态感知开发指导
简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明