1# @ohos.multimodalAwareness.motion (动作感知) 2<!--Kit: Multimodal Awareness Kit--> 3<!--Subsystem: MultimodalAwareness--> 4<!--Owner: @dilligencer--> 5<!--Designer: @zou_ye--> 6<!--Tester: @judan--> 7<!--Adviser: @hu-zhiqiong--> 8 9本模块，提供对用户行为、动作的感知能力，包括用户的手势、动作等。 10 11> **说明：** 12> 13> 本模块首批接口从API version 15开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14 15 16## 导入模块 17 18```ts 19import { motion } from '@kit.MultimodalAwarenessKit'; 20``` 21 22## OperatingHandStatus 23 24触控操作手状态信息。 25 26**系统能力**：SystemCapability.MultimodalAwareness.Motion 27 28| 名称 | 值 | 说明 | 29| ------------------- | ---- | ---------------------- | 30| UNKNOWN_STATUS | 0 | 表示未识别。 | 31| LEFT_HAND_OPERATED | 1 | 表示触控操作手是左手。 | 32| RIGHT_HAND_OPERATED | 2 | 表示触控操作手是右手。 | 33 34## HoldingHandStatus<sup>20+</sup> 35 36手机握持手状态信息，表示握持手状态变化感知事件的结果。订阅握持手状态变化感知事件后，返回当前握持手状态信息。 37 38**系统能力**：SystemCapability.MultimodalAwareness.Motion 39 40| 名称 | 值 | 说明 | 41| --------------- | ---- | -------------- | 42| NOT_HELD | 0 | 表示未握持。 | 43| LEFT_HAND_HELD | 1 | 表示左手握持。 | 44| RIGHT_HAND_HELD | 2 | 表示右手握持。 | 45| BOTH_HANDS_HELD | 3 | 表示双手握持。 | 46| UNKNOWN_STATUS | 16 | 表示未识别。 | 47 48## motion.on('operatingHandChanged') 49 50on(type: 'operatingHandChanged', callback: Callback<OperatingHandStatus>): void 51 52订阅触控操作手感知事件。 53 54此功能如果设备不支持，将返回801错误码。 55 56**需要权限**：ohos.permission.ACTIVITY_MOTION 或 ohos.permission.DETECT_GESTURE 57 58**系统能力**：SystemCapability.MultimodalAwareness.Motion 59 60**参数**： 61 62| 参数名 | 类型 | 必填 | 说明 | 63| -------- | -------------------------------- | ---- | ------------------------------------------------------------ | 64| type | string | 是 | 事件类型。type为“operatingHandChanged”，表示操作手状态变化。 | 65| callback | Callback<[OperatingHandStatus](#operatinghandstatus)> | 是 | 回调函数，返回操作手结果。 | 66 67**错误码**： 68 69以下错误码的详细介绍请参见[动作感知错误码](errorcode-motion.md)和[通用错误码](../errorcode-universal.md)。 70 71| 错误码ID | 错误信息 | 72| -------- | ------------------------------------------------------------ | 73| 201 | Permission denied. An attempt was made to subscribe operatingHandChanged event forbidden by permission: ohos.permission.ACTIVITY_MOTION or ohos.permission.DETECT_GESTURE. | 74| 401 | Parameter error. Parameter verification failed. | 75| 801 | Capability not supported. Function can not work correctly due to limited device capabilities. | 76| 31500001 | Service exception. Possible causes: 1. A system error, such as null pointer, container-related exception; 2. N-API invocation exception, invalid N-API status. | 77| 31500002 | Subscription failed. Possible causes: 1. Callback registration failure; 2. Failed to bind native object to js wrapper; 3. N-API invocation exception, invalid N-API status; 4. IPC request exception. | 78 79**示例**： 80 81```ts 82import { BusinessError } from '@kit.BasicServicesKit'; 83import { Callback } from '@ohos.base'; 84 85let callback:Callback<motion.OperatingHandStatus> = (data:motion.OperatingHandStatus) => { 86 console.info('callback success' + data); 87}; 88 89try { 90 motion.on('operatingHandChanged', callback); 91 console.info("on succeeded"); 92} catch (err) { 93 let error = err as BusinessError; 94 console.error("Failed on and err code is " + error.code); 95} 96``` 97 98## motion.off('operatingHandChanged') 99 100off(type: 'operatingHandChanged', callback?: Callback<OperatingHandStatus>): void 101 102取消订阅触控操作手感知事件。 103 104**需要权限**：ohos.permission.ACTIVITY_MOTION 或 ohos.permission.DETECT_GESTURE 105 106**系统能力**：SystemCapability.MultimodalAwareness.Motion 107 108**参数**： 109 110| 参数名 | 类型 | 必填 | 说明 | 111| -------- | -------------------------------- | ---- | ------------------------------------------------------------ | 112| type | string | 是 | 事件类型。type为“operatingHandChanged”，表示操作手状态变化。 | 113| callback | Callback<[OperatingHandStatus](#operatinghandstatus)> | 否 | 回调函数，返回操作手结果。 | 114 115**错误码**： 116 117以下错误码的详细介绍请参见[动作感知错误码](errorcode-motion.md)和[通用错误码](../errorcode-universal.md)。 118 119| 错误码ID | 错误信息 | 120| -------- | ------------------------------------------------------------ | 121| 201 | Permission denied. An attempt was made to unsubscribe operatingHandChanged event forbidden by permission: ohos.permission.ACTIVITY_MOTION or ohos.permission.DETECT_GESTURE. | 122| 401 | Parameter error. Parameter verification failed. | 123| 801 | Capability not supported. Function can not work correctly due to limited device capabilities. | 124| 31500001 | Service exception. Possible causes: 1. A system error, such as null pointer, container-related exception; 2. N-API invocation exception, invalid N-API status. | 125| 31500003 | Unsubscription failed. Possible causes: 1. Callback failure; 2. N-API invocation exception, invalid N-API status; 3. IPC request exception. | 126 127**示例**： 128 129```ts 130import { BusinessError } from '@kit.BasicServicesKit'; 131 132try { 133 motion.off('operatingHandChanged'); 134 console.info("off succeeded"); 135} catch (err) { 136 let error = err as BusinessError; 137 console.error("Failed off and err code is " + error.code); 138} 139``` 140 141## motion.getRecentOperatingHandStatus() 142 143getRecentOperatingHandStatus(): OperatingHandStatus 144 145获取最新触控操作手状态。 146 147**需要权限**：ohos.permission.ACTIVITY_MOTION 或 ohos.permission.DETECT_GESTURE 148 149**系统能力**：SystemCapability.MultimodalAwareness.Motion 150 151**返回值**： 152 153| 类型 | 说明 | 154| ----------------------------- | ------------------------------------ | 155| [OperatingHandStatus](#operatinghandstatus) | 返回触控操作手状态信息。 | 156 157**错误码**： 158 159以下错误码的详细介绍请参见[动作感知错误码](errorcode-motion.md)和[通用错误码](../errorcode-universal.md)。 160 161| 错误码ID | 错误信息 | 162| -------- | ------------------------------------------------------------ | 163| 201 | Permission denied. An attempt was made to get the recent operating hand status forbidden by permission: ohos.permission.ACTIVITY_MOTION or ohos.permission.DETECT_GESTURE. | 164| 801 | Capability not supported. Function can not work correctly due to limited device capabilities. | 165| 31500001 | Service exception. Possible causes: 1. A system error, such as null pointer, container-related exception; 2. N-API invocation exception, invalid N-API status. | 166 167**示例**： 168 169```ts 170import { BusinessError } from '@kit.BasicServicesKit'; 171 172try { 173 let data:motion.OperatingHandStatus = motion.getRecentOperatingHandStatus(); 174 console.info('get success' + data); 175} catch (err) { 176 let error = err as BusinessError; 177 console.error("Failed get and err code is " + error.code); 178} 179``` 180 181## motion.on('holdingHandChanged') <sup>20+</sup> 182 183on(type: 'holdingHandChanged', callback: Callback<HoldingHandStatus>): void 184 185订阅握持手状态变化感知事件。 186 187**需要权限**：ohos.permission.DETECT_GESTURE 188 189**系统能力**：SystemCapability.MultimodalAwareness.Motion 190 191**参数** 192 193| 参数名 | 类型 | 必填 | 说明 | 194| -------- | ------------------------------------------------- | ---- | -------------------------------------- | 195| type | string | 是 | 事件类型，type为"holdingHandChanged"。 | 196| callback | Callback<[HoldingHandStatus](#holdinghandstatus20)> | 是 | 回调函数，返回握持手状态结果。 | 197 198**错误码** 199 200以下错误码的详细介绍请参见[动作感知错误码](errorcode-motion.md)和[通用错误码](../errorcode-universal.md)。 201 202| 错误码ID | 错误信息 | 203| -------- | ------------------------------------------------------------ | 204| 201 | Permission denied. An attempt was made to subscribe holdingHandChanged event forbidden by permission: ohos.permission.DETECT_GESTURE. | 205| 801 | Capability not supported. Function can not work correctly due to limited device capabilities. | 206| 31500001 | Service exception. Possible causes: 1. A system error, such as null pointer, container-related exception; 2. N-API invocation exception, invalid N-API status. | 207| 31500002 | Subscription failed. Possible causes: 1. Callback registration failure; 2. Failed to bind native object to js wrapper; 3. N-API invocation exception, invalid N-API status; 4. IPC request exception. | 208 209**示例** 210 211```typescript 212import { BusinessError } from '@kit.BasicServicesKit'; 213import { Callback } from '@ohos.base'; 214 215let callback:Callback<motion.HoldingHandStatus> = (data:motion.HoldingHandStatus) => { 216 console.info('callback success: ' + data); 217}; 218 219try { 220 motion.on('holdingHandChanged', callback); 221 console.info('on succeeded'); 222} catch (err) { 223 let error = err as BusinessError; 224 console.error('Failed on; err code = ' + error.code); 225} 226``` 227 228## motion.off('holdingHandChanged') <sup>20+</sup> 229 230off(type: 'holdingHandChanged', callback?: Callback<HoldingHandStatus>): void 231 232取消订阅握持手状态变化感知事件。 233 234**需要权限**：ohos.permission.DETECT_GESTURE 235 236**系统能力**：SystemCapability.MultimodalAwareness.Motion 237 238**参数** 239 240| 参数名 | 类型 | 必填 | 说明 | 241| -------- | ------------------------------------------------- | ---- | ---------------------------------------------- | 242| type | string | 是 | 事件类型，type为"holdingHandChanged"。 | 243| callback | Callback<[HoldingHandStatus](#holdinghandstatus20)> | 否 | 需取消的回调函数。省略则移除该事件的所有回调。 | 244 245**错误码** 246 247以下错误码的详细介绍请参见[动作感知错误码](errorcode-motion.md)和[通用错误码](../errorcode-universal.md)。 248 249| 错误码ID | 错误信息 | 250| -------- | ------------------------------------------------------------ | 251| 201 | Permission denied. An attempt was made to unsubscribe holdingHandChanged event forbidden by permission: ohos.permission.DETECT_GESTURE. | 252| 801 | Capability not supported. Function can not work correctly due to limited device capabilities. | 253| 31500001 | Service exception. Possible causes: 1. A system error, such as null pointer, container-related exception; 2. N-API invocation exception, invalid N-API status. | 254| 31500003 | Unsubscription failed. Possible causes: 1. Callback failure; 2. N-API invocation exception, invalid N-API status; 3. IPC request exception. | 255 256**示例** 257 258```typescript 259import { BusinessError } from '@kit.BasicServicesKit'; 260 261try { 262 motion.off('holdingHandChanged'); // 移除所有同类订阅 263 console.info('off succeeded'); 264} catch (err) { 265 let error = err as BusinessError; 266 console.error('Failed off; err code = ' + error.code); 267} 268``` 269