@capacitor/share

本项目基于 @capacitor/[email protected] 开发。

简介

@capacitor/share 是 capacitor 生态系统中的核心插件，为跨平台应用开发提供设备差异化适配能力，兼容 capacitor 的 Android、iOS 等主流移动平台及浏览器环境，本文档主要说明在 OpenHarmony 系统中的使用。

该插件提供了调用系统分享面板分享内容的能力，支持分享文本、URL、图片和其它文件，满足移动应用中内容分享的常见场景需求。

支持平台

• OpenHarmony：5.0+

下载安装

通过命令行或手动引入即可快速安装插件，支持从npm仓库获取。

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

以下两种方式中任选其一即可，无需重复操作：

npm安装：

# 安装插件
npm install @capacitor/share

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/share

手动引入安装

根据插件源码中 plugin.xml 配置在项目中引入插件：

1. 添加插件配置

根据 plugin.xml 的 config-json 项，通过 target 字段找到 entry 模块中 capacitor.plugins.json 文件，并根据 param 标签添加配置如下：

{
    "pkg": "@capacitor/share",
    "classpath": "Share"
}

2. 修改 CMake 配置

根据 plugin.xml 的 CMakeLists 项，通过 modules-name 字段找到模块 capacitor，路径为 target 字段的 CMakeLists.txt 文件，并根据 param 标签添加 add_subdirectory 和 target_link_libraries 如下：

#START_ADD_SUBDIRECTORY
// ...
add_subdirectory(Share)
// ...
#END_ADD_SUBDIRECTORY

// ...

target_link_libraries(capacitor PUBLIC
  "-Wl,--whole-archive"
  // ...
  Share
  // ...
  "-Wl,--no-whole-archive"
)

3. 复制源码文件

根据 plugin.xml 的 source-file 项，根据 src 字段找到需要复制的文件，并根据 modules-name 字段和 target-dir 字段找到文件复制的具体模块和目录：

将源码中 src/main/cpp/Share 目录下的 Share.h、Share.cpp、CMakeLists.txt 文件引入到 capacitor 模块中 src/main/cpp/Share 目录下。

将源码中 src/main/ets/components/Share 目录下的 ShareAction.ets 文件引入到 capacitor 模块中 src/main/ets/components/Share 目录下。

4. 添加 ArkTS 配置

在 capacitor 模块的 build-profile.json5 文件中，buildOption/arkOptions/runtimeOnly/sources 配置项数组中加入步骤 3 中拷贝的 ets 文件路径：

"buildOption":{
  // ...
  "arkOptions": {
    "runtimeOnly": {
      "sources": [
        // ...
        "./src/main/ets/components/Share/ShareAction.ets"
        // ...
      ]
    }
  }
}

卸载

# 卸载 share 插件
hionic plugin remove @capacitor/share

约束与限制

兼容性

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

1. SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

权限要求

依赖系统分享功能，无需额外权限。

使用示例

基础示例：分享内容

import { Share } from '@capacitor/share';

// 仅分享文本
await Share.share({
  text: 'Really awesome thing you need to see right meow',
});

// 仅分享 URL
await Share.share({
  url: 'http://ionicframework.com/',
});

// 分享文本和 URL
await Share.share({
  title: 'Ionic Framework',
  text: 'Really awesome thing you need to see right meow',
  url: 'http://ionicframework.com/',
});

使用说明

接口方法

| 方法名 | 返回类型 | 描述 | 备注 | | ---- | ---- | ---- | ---- | | canShare() | Promise<CanShareResult> | 检查是否支持分享 | | | share(options: ShareOptions) | Promise<ShareResult> | 显示分享面板，分享内容 | API 18 及以上版本支持返回用户选择的应用标识符 |

数据结构

CanShareResult

调用 canShare 方法时的返回对象

| 属性 | 类型 | 描述 | | ------------ | -------- | ------------------------------------------------------------ | | value | boolean | 是否支持分享 |

ShareOptions

调用 share 方法时的参数对象

| 属性 | 类型 | 描述 | | ----------- | -------- | ------------------- | | title | string | 为任何消息设置一个标题。如果通过电子邮件分享，这将成为邮件的主题。 | | text | string | 设置一些要分享的文本。 | | url | string | 设置一个要分享的 URL，可以是 http、https 或 file:// URL。 | | files | string[] | 待分享文件的 file:// URL 数组。 | | dialogTitle | string | 为分享面板设置标题。 |

ShareResult

调用 share 方法时的返回对象

| 属性 | 类型 | 描述 | | ------------ | -------- | ------------------------------------------------------------ | | activityType | string | 接收分享操作的应用程序的标识符。 API 18+ 支持 |

其它

本插件依赖设备的系统分享功能，分享能力取决于设备上已安装的应用。

目录结构

|---- 项目根目录
|     |---- src
|           |---- main
|                 |---- cpp
|                       |---- Share   # 插件核心 C++ 实现
|                             |---- Share.cpp
|                             |---- Share.h
|                             |---- CMakeLists.txt
|                 |---- ets
|                       |---- components
|                             |---- Share   # ArkTS 组件实现
|                                   |---- ShareAction.ets
|     |---- README.md              # 说明文档
|     |---- package.json           # npm 配置文件
|     |---- plugin.xml             # capacitor 插件配置
|     |---- LICENSE                # 许可证文件

贡献代码

使用过程中发现任何问题都可以提 Issue，当然，也非常欢迎发 PR 共建。

许可证

本插件基于 MIT License 开源，详见 LICENSE 文件。