holding

Flutter 握持手感知插件，支持 HarmonyOS/OpenHarmony 平台。通过系统多模态感知能力（@kit.MultimodalAwarenessKit 的 motion.on('holdingHandChanged')）订阅握持手状态变化（未握持 / 左手 / 右手 / 双手 / 未识别）。

---

1. 安装与使用

1.1 安装方式

在工程目录的 pubspec.yaml 中添加依赖：

方式一：Pub 依赖（推荐）

dependencies:
  holding: ^0.0.1

方式二：Git 依赖

dependencies:
  holding:
    git:
      url: https://gitcode.com/oh-flutter/holding-harmony.git
      path: .
      ref: main

方式三：本地路径依赖

dependencies:
  holding:
    path: ../holding

然后执行：

flutter pub get

1.2 使用案例

使用示例见 holding/example 目录。

---

2. 约束与限制

2.1 兼容性

在以下版本中已测试通过：

• Flutter: 3.35.8-ohos-0.0.2
• Dart: 3.9.2
• SDK: 5.1.0(18)
• IDE: DevEco Studio 6.0.2 Release
• ROM: 6.0.0.130 SP15

2.2 权限要求

握持手感知需要以下权限。在 插件 HAR 模块 的 ohos/src/main/module.json5 中已声明：

"requestPermissions": [
  {
    "name": "ohos.permission.DETECT_GESTURE",
    "reason": "$string:detect_gesture_reason"
  },
  {
    "name": "ohos.permission.ACTIVITY_MOTION",
    "reason": "$string:activity_motion_reason"
  }
]

若使用 entry 工程（如 example/ohos），需在 entry 的 module.json5 中申请上述权限，并在 entry/src/main/resources/base/element/string.json 中提供说明文案，例如：

{
  "string": [
    { "name": "detect_gesture_reason", "value": "用于识别握持手状态" },
    { "name": "activity_motion_reason", "value": "用于活动与运动感知" }
  ]
}

---

3. API

“ohos Support” 列：yes 表示 OHOS 支持，no 表示不支持。

3.1 Holding（主入口）

Name	return	Description	Type	ohos Support
subscribeHoldingHand(SubscribeHoldingHandOptions options)	void	订阅握持手状态变化，通过 options.onChange 接收状态	function	yes
unsubscribeHoldingHand(UnsubscribeHoldingHandOptions? options)	void	取消订阅握持手状态变化	function	yes

3.2 类型与回调

Name	return	Description	Type	ohos Support
HoldingHandChangeCallback(HoldingHandStatus status)	void	握持手状态变化时的回调签名	typedef	yes
SubscribeHoldingHandOptions	-	订阅握持手时的参数：onChange（必填）、success、fail、complete	class	yes
UnsubscribeHoldingHandOptions	-	取消订阅时的参数：success、fail、complete	typedef	yes
SubscribeOptionsBase	-	通用选项基类：success、fail、complete 回调	class	yes

3.3 HoldingHandStatus（枚举）

Name	Description	Type	ohos Support
HoldingHandStatus.none	未握持（系统码 0）	enum	yes
HoldingHandStatus.left	左手握持（系统码 1）	enum	yes
HoldingHandStatus.right	右手握持（系统码 2）	enum	yes
HoldingHandStatus.both	双手握持（系统码 3）	enum	yes
HoldingHandStatus.unknown	未识别（系统码 16）	enum	yes
HoldingHandStatus.code	鸿蒙返回的整型状态值	int	yes
HoldingHandStatus.fromCode(int code)	从系统状态码解析为枚举	static	yes

---

4. 属性

4.1 SubscribeHoldingHandOptions

Name	Description	Type	ohos Support
onChange	握持手状态变化时回调（必填）	HoldingHandChangeCallback	yes
success	订阅成功回调	void Function()?	yes
fail	订阅失败回调，参数为错误信息	void Function(String errMsg)?	yes
complete	完成回调（成功或失败都会调用），参数为 errMsg	void Function(String errMsg)?	yes

4.2 UnsubscribeHoldingHandOptions / SubscribeOptionsBase

Name	Description	Type	ohos Support
success	操作成功回调	void Function()?	yes
fail	操作失败回调，参数为错误信息	void Function(String errMsg)?	yes
complete	完成回调，参数为 errMsg	void Function(String errMsg)?	yes

---

5. 遗留问题

无。

---

6. 其他

• 实现原理：Dart 通过 MethodChannel（holding）调用原生订阅/取消订阅，通过 EventChannel（holding/events）接收状态事件流；OHOS 端使用 motion.on('holdingHandChanged') / motion.off('holdingHandChanged')。

---

7. 开源协议

本项目采用 Apache License 2.0，详见 LICENSE 文件。