gesturesshare

Flutter 隔空传送分享插件，支持 HarmonyOS/OpenHarmony 平台。通过系统分享能力（@kit.ShareKit 的 harmonyShare.on('gesturesShare')）注册隔空传送监听，在用户触发隔空传送手势时自动分享指定本地图片，并可携带 App Linking 链接、标题与描述。

---

1. 安装与使用

1.1 安装方式

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

方式一：Pub 依赖（推荐）

dependencies:
  gesturesshare: ^0.0.1

方式二：Git 依赖

dependencies:
  gesturesshare:
    git:
      url: https://gitcode.com/你的仓库/gesturesshare.git
      path: .
      ref: main

方式三：本地路径依赖

dependencies:
  gesturesshare:
    path: ../gesturesshare

然后执行：

flutter pub get

1.2 使用案例

使用示例见 gesturesshare/example 目录，包含「分享福卡」「分享图片」「自定义参数」等场景。

更详细的参数说明与示例见根目录 使用说明.md。

---

2. 约束与限制

2.1 兼容性

• 本插件仅支持 OHOS 平台，其他平台调用相关接口会未实现或报错。
• 建议在以下环境中使用：
  • Flutter for OpenHarmony（如 3.35.x-ohos）
  • Dart: 3.9.x
  • HarmonyOS / OpenHarmony 设备需支持隔空传送能力。

2.2 权限与能力

• 隔空传送为系统级分享能力，一般无需在应用中单独申请额外权限。
• 图片路径需为应用可访问的本地文件路径（如应用私有目录、已授权路径等）。

---

3. API

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

3.1 Gesturesshare（主入口）

Name	return	Description	Type	ohos Support
getPlatformVersion()	Future<String?>	获取平台版本信息	function	yes
registerGesturesShare(RegisterGesturesShareOptions options)	Future<void>	注册隔空传送分享监听，用户做隔空传送手势时分享指定内容	function	yes
unregisterGesturesShare()	Future<void>	取消隔空传送分享监听	function	yes
onShareTriggered	Stream<GesturesShareResult>	隔空传送实际触发后的分享结果事件流	getter	yes

3.2 类型与数据类

Name	Description	Type	ohos Support
RegisterGesturesShareOptions	注册参数：imagePath（必填）、appLink、title、description	class	yes
GesturesShareResult	分享触发结果：success、errCode、errMsg	class	yes

---

4. 属性

4.1 RegisterGesturesShareOptions

Name	Description	Type	ohos Support
imagePath	要分享的图片本地路径（必填）	String	yes
appLink	App Linking 链接，填写后以「链接 + 缩略图」形式分享	String?	yes
title	分享标题	String?	yes
description	分享描述	String?	yes

4.2 GesturesShareResult

Name	Description	Type	ohos Support
success	是否分享成功	bool	yes
errCode	错误码（失败时有值）	int?	yes
errMsg	结果或错误信息	String	yes

---

5. 遗留问题

无。

---

6. 其他

• 实现原理：Dart 通过 MethodChannel（gesturesshare）调用原生注册/注销；原生通过同一 Channel 向 Flutter 回调 onShareTriggered 事件。OHOS 端使用 harmonyShare.on('gesturesShare', capability, callback) / harmonyShare.off('gesturesShare', capability)，分享内容通过 systemShare.SharedData 构建（纯图片为 IMAGE 类型，带链接为 HYPERLINK 类型）。
• 插件实现 AbilityAware，使用 UIAbility.context 获取窗口以正确注册隔空传送能力。

---

7. 开源协议

本项目采用 Apache License 2.0，版权归属坚果派。详见 LICENSE 文件。