{"_id":"@cordova-ohos/cordova-plugin-x-socialsharing","_rev":"3-60ef42f91fa216aa83b1a3fc64cf3e01","name":"@cordova-ohos/cordova-plugin-x-socialsharing","dist-tags":{"latest":"6.0.5"},"versions":{"6.0.4":{"name":"@cordova-ohos/cordova-plugin-x-socialsharing","version":"6.0.4","keywords":["cordova","x-socialsharing","ecosystem:cordova","cordova-openharmony"],"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-x-socialsharing@6.0.4","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"}],"bugs":{"url":"https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-x-socialsharing/issues"},"dist":{"shasum":"bece2577b7cff6d5690845a11f883e7191357a69","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-x-socialsharing/-/cordova-plugin-x-socialsharing-6.0.4.tgz","fileCount":10,"integrity":"sha512-G3f9XQTb5fLtH8I7dk9yZop2meT/ErG4tpkFxZbQsGjqHrmNYM43jqvEA5q1nWRSsWREpiIDM3zGH5mDfLgDtg==","signatures":[{"sig":"MEYCIQCTTWHHZwZk2gtQ52fcv9kcqL7sYj9ow7iD4IiDxzZFcgIhAN0Mw8ctk/6U30M4RHrYmVOPDSB3HUj/39H/zoxdUVBt","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":87378},"cordova":{"id":"cordova-plugin-x-socialsharing","platforms":["ohos"]},"engines":{"cordovaDependencies":{"6.0.4":{"hcordova":">=1.0.0","@cordova-ohos/ohos":">=2.0.0"}}},"gitHead":"dadede839580307919c440b8129f6aac1f0ee4ed","_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"repository":{"url":"gitcode:OpenHarmony-Cordova/cordova-plugin-x-socialsharing","type":"git"},"_npmVersion":"10.5.1","description":"Cordova x-socialsharing Plugin","directories":{},"_nodeVersion":"22.0.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/cordova-plugin-x-socialsharing_6.0.4_1774228497441_0.3952766578450073","host":"s3://npm-registry-packages-npm-production"}},"6.0.5":{"name":"@cordova-ohos/cordova-plugin-x-socialsharing","version":"6.0.5","description":"Cordova X-SocialSharing Plugin","cordova":{"id":"cordova-plugin-x-socialsharing","platforms":["ohos"]},"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-x-socialsharing"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-x-socialsharing/issues"},"keywords":["cordova","x-socialsharing","ecosystem:cordova","cordova-openharmony"],"engines":{"cordovaDependencies":{"6.0.5":{"@cordova-ohos/ohos":">=2.0.0","hcordova":">=1.0.0"}}},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-x-socialsharing@6.0.5","gitHead":"07c3ec2ea2baae3b31fd8cc31ce82e59aa50a14f","_nodeVersion":"22.0.0","_npmVersion":"10.5.1","dist":{"integrity":"sha512-QUcL6uyiPPV1Q7TAUxZrnrMUCXKc5ldHPySQgkuJC643XXnu1HpEVdM/S3DY+BVwlG+jcAvT9g3766BWHt7eIg==","shasum":"48d65be563ca5a39c891f3b8f67a20152105af73","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-x-socialsharing/-/cordova-plugin-x-socialsharing-6.0.5.tgz","fileCount":11,"unpackedSize":144572,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICWQSUKf8e7HUPi5rpz42d39XYmnW1kaI7s6LXtigtU2AiEAvO1WAey4tJc+NaWjiM0Bqc/4kyXI82S34iPzIlMXSkQ="}]},"_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"directories":{},"maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"},{"name":"hcordova","email":"chenlihuiabc@163.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cordova-plugin-x-socialsharing_6.0.5_1785150744845_0.2762802188509943"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-23T01:14:57.367Z","modified":"2026-07-27T11:12:25.175Z","6.0.4":"2026-03-23T01:14:57.609Z","6.0.5":"2026-07-27T11:12:24.977Z"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-x-socialsharing/issues"},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","keywords":["cordova","x-socialsharing","ecosystem:cordova","cordova-openharmony"],"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-x-socialsharing"},"description":"Cordova X-SocialSharing Plugin","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"},{"name":"hcordova","email":"chenlihuiabc@163.com"}],"readme":"# <center>cordova-plugin-x-socialsharing</center>\r\n\r\n[![zh-CN](https://img.shields.io/badge/lang-中文-blue.svg)](README.md)\r\n[![en](https://img.shields.io/badge/lang-English-blue.svg)](README.en.md)\r\n\r\n本项目基于 [cordova-plugin-x-socialsharing@6.0.4](https://www.npmjs.com/package/cordova-plugin-x-socialsharing/v/6.0.4) 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。\r\n\r\n- [cordova-plugin-x-socialsharing](#cordova-plugin-x-socialsharing)\r\n  - [简介](#简介)\r\n  - [功能特性](#功能特性)\r\n  - [OHOS 平台特性](#ohos-平台特性)\r\n  - [支持平台](#支持平台)\r\n  - [前置准备](#前置准备)\r\n  - [下载安装](#下载安装)\r\n    - [前提条件](#前提条件)\r\n    - [基础安装（推荐）](#基础安装推荐)\r\n    - [从 GitCode 安装](#从-gitcode-安装)\r\n    - [离线安装（本地包）](#离线安装本地包)\r\n    - [安装后验证](#安装后验证)\r\n    - [卸载插件](#卸载插件)\r\n  - [OHOS 配置](#ohos-配置)\r\n    - [1. 文件访问权限配置](#1-文件访问权限配置)\r\n    - [2. 邮件应用配置](#2-邮件应用配置)\r\n  - [约束与限制](#约束与限制)\r\n    - [兼容性](#兼容性)\r\n  - [使用示例](#使用示例)\r\n    - [1. 检查分享插件是否存在](#1-检查分享插件是否存在)\r\n    - [2. 核心分享 API（多场景示例）](#2-核心分享-api多场景示例)\r\n    - [3. 检查邮件应用是否可用](#3-检查邮件应用是否可用)\r\n    - [4. 拉起邮件应用发送邮件](#4-拉起邮件应用发送邮件)\r\n    - [5. 拉起短信应用发送短信](#5-拉起短信应用发送短信)\r\n    - [6. 判断是否可以拉起指定应用](#6-判断是否可以拉起指定应用)\r\n    - [7. 拉起指定应用](#7-拉起指定应用)\r\n  - [使用说明](#使用说明)\r\n    - [1. 核心 API 说明](#1-核心-api-说明)\r\n      - [1.1 检查插件是否可用](#11-检查插件是否可用)\r\n      - [1.2 核心分享 API](#12-核心分享-api)\r\n      - [1.3 邮件应用可用性检测](#13-邮件应用可用性检测)\r\n      - [1.4 拉起邮件应用](#14-拉起邮件应用)\r\n      - [1.5 拉起短信应用](#15-拉起短信应用)\r\n      - [1.6 判断是否可拉起指定应用](#16-判断是否可拉起指定应用)\r\n      - [1.7 拉起指定应用](#17-拉起指定应用)\r\n    - [2. 常见问题（FAQ）](#2-常见问题faq)\r\n      - [Q1: 调用插件 API 后无反应怎么办？](#q1-调用插件-api-后无反应怎么办)\r\n      - [Q2: 本地文件/沙箱图片分享失败怎么办？](#q2-本地文件沙箱图片分享失败怎么办)\r\n      - [Q3: 邮件应用无法拉起或发送邮件怎么办？](#q3-邮件应用无法拉起或发送邮件怎么办)\r\n      - [Q4: 无法拉起指定应用怎么办？](#q4-无法拉起指定应用怎么办)\r\n      - [Q5: 分享回调显示成功，但实际未分享成功怎么办？](#q5-分享回调显示成功但实际未分享成功怎么办)\r\n    - [3. 注意事项](#3-注意事项)\r\n  - [目录结构](#目录结构)\r\n  - [贡献代码](#贡献代码)\r\n  - [许可证](#许可证)\r\n  - [官方资源](#官方资源)\r\n\r\n\r\n## 简介\r\n\r\n`cordova-plugin-x-socialsharing` 是一款功能强大的 Cordova 社交分享插件，支持跨平台（Android、iOS、Windows、Browser、OHOS）调用设备原生社交应用，实现文本、图片、链接、文件等内容的分享功能。在 OHOS 系统中，插件直接调用 OHOS 系统的分享面板提供分享服务，无需额外适配底层分享能力，并提供灵活的分享配置，可满足各类应用的社交传播需求。本文档主要介绍该插件在 OHOS 系统中的应用、安装、配置、使用方法及注意事项，帮助开发者快速集成社交分享功能。\r\n\r\n## 功能特性\r\n\r\n- **多平台兼容**：支持 Android、iOS、Windows、Browser 多平台，重点适配 OHOS 系统，调用系统原生分享面板，体验流畅\r\n\r\n- **多内容类型支持**：可分享文本、单张/多张图片（在线图片、base64 图片、本地沙箱图片）、网页链接、本地文件（如 PDF、文档、视频等），覆盖各类分享场景\r\n\r\n- **主流社交应用兼容**：支持微信（好友/朋友圈）、QQ（好友/空间）、微博等主流社交应用，适配 OHOS 系统中已安装的各类社交应用\r\n\r\n- **灵活配置能力**：可指定分享目标应用、自定义分享标题/描述、设置分享回调监听，精准匹配应用业务需求\r\n\r\n- **文件分享能力**：支持跨应用分享本地存储的各类文件，适配办公、教育、媒体类应用的文件传输需求\r\n\r\n- **轻量化设计**：插件体积小，无冗余依赖，集成后对应用性能影响极小，不占用过多设备资源\r\n\r\n- **多场景拓展**：除社交分享外，支持拉起邮件、短信应用，可判断指定应用是否可拉起并实现定向调用\r\n\r\n- **双调用方式**：支持回调函数与 Promise 两种调用方式，推荐使用 Promise 简化异步逻辑，降低开发难度\r\n\r\n## OHOS 平台特性\r\n\r\n该插件在 OHOS 平台的实现有别于 Android/iOS 平台，核心特性如下，需重点关注：\r\n\r\n- 调用 OHOS 系统原生分享面板，无需单独适配各社交应用，依赖系统自身的分享能力，兼容性更强\r\n\r\n- 支持 OHOS 系统自带邮件、短信应用的拉起与使用，邮件应用需完成单独配置后方可正常使用\r\n\r\n- 可通过 URI 定向判断、拉起指定应用，满足特定场景下的应用跳转与内容分享需求\r\n\r\n- 支持本地沙箱路径图片、在线图片、base64 图片的分享，适配 OHOS 系统的文件访问权限规范\r\n\r\n## 支持平台\r\n\r\n- **OHOS**（适配系统原生分享面板，支持邮件、短信、社交应用分享）\r\n\r\n- **Android/iOS**（调用原生社交应用分享，详情参考官方指南）\r\n\r\n- **Windows/Browser**（基础分享功能支持，具体适配细节参考官方文档）\r\n\r\n## 前置准备\r\n\r\n在集成插件前，需确保开发环境满足基础要求，完成必要的前置配置，具体步骤如下：\r\n\r\n- 已安装 Node.js（v14.0.0 及以上）和 npm（v6.0.0 及以上），可通过 `node -v` 和 `npm -v` 命令验证版本；\r\n\r\n- 已全局安装 HCordova CLI（v10.0.0 及以上），用于插件的安装、卸载和管理；\r\n\r\n- 已创建 Cordova 项目（若尚未创建，可通过 `hcordova create MyShareApp com.example.shareapp 社交分享示例应用` 命令快速创建）；\r\n\r\n- OHOS 平台需确保应用已获取文件访问权限（若涉及本地文件、沙箱图片分享），避免因权限不足导致分享失败；\r\n\r\n- 若需使用邮件分享功能，需提前配置 OHOS 系统邮件应用，确保邮件应用可正常使用。\r\n\r\n## 下载安装\r\n\r\n通过 HCordova CLI 即可快速安装插件，支持全平台安装或指定 OHOS 平台安装，安装流程简洁高效，安装后可通过命令验证安装结果。\r\n\r\n### 前提条件\r\n\r\n安装插件前，需先安装 HCordova CLI，执行以下命令安装：\r\n\r\n```bash\r\nnpm install -g hcordova\r\n```\r\n\r\n### 基础安装（推荐）\r\n\r\n在 Cordova 项目根目录执行以下命令，插件会自动处理各平台依赖与基础配置，默认安装最新版本：\r\n\r\n```bash\r\n# 安装最新版本（全平台）\r\nhcordova plugin add cordova-plugin-x-socialsharing\r\n\r\n# 安装指定 OHOS 平台\r\nhcordova plugin add cordova-plugin-x-socialsharing --platform ohos\r\n\r\n# 安装指定版本（仅 OHOS 平台）\r\nhcordova plugin add cordova-plugin-x-socialsharing@1.0.0 --platform ohos\r\n```\r\n\r\n### 从 GitCode 安装\r\n\r\n若需使用开发中的最新功能，可直接从 GitCode 仓库安装，仅适配 OHOS 平台：\r\n\r\n```bash\r\n# 仅支持 OHOS 平台\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-x-socialsharing.git --platform ohos\r\n\r\n# 指定标签/分支安装\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-x-socialsharing.git@develop --platform ohos\r\n```\r\n\r\n### 离线安装（本地包）\r\n\r\n适用于无网络环境，先下载插件包到本地，再执行离线安装：\r\n\r\n```bash\r\n# 下载插件包到本地（示例路径：../Downloads/cordova-plugin-x-socialsharing）\r\n# 执行离线安装\r\nhcordova plugin add ../Downloads/cordova-plugin-x-socialsharing  --platform ohos\r\n```\r\n\r\n### 安装后验证\r\n\r\n安装完成后，可通过以下命令验证插件是否成功添加到项目中：\r\n\r\n```bash\r\n# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装\r\nhcordova plugin list\r\n```\r\n\r\n\r\n\r\n### 卸载插件\r\n\r\n如需移除插件，执行以下命令即可清理相关配置与依赖，支持全平台卸载或指定 OHOS 平台卸载：\r\n\r\n```bash\r\n# 全平台卸载\r\nhcordova plugin remove cordova-plugin-x-socialsharing\r\n\r\n# 指定 OHOS 平台卸载\r\nhcordova plugin remove cordova-plugin-x-socialsharing --platform ohos\r\n```\r\n\r\n## OHOS 配置\r\n\r\nOHOS 平台集成插件后，大部分功能可直接使用，无需额外复杂配置，以下为特殊场景的配置说明：\r\n\r\n### 1. 文件访问权限配置\r\n\r\n若涉及本地文件、沙箱路径图片分享，需在项目的 module.json5 文件中添加文件访问权限，确保插件可正常读取本地文件：\r\n\r\n```json\r\n\"requestPermissions\": [\r\n    {\r\n        \"name\": \"ohos.permission.READ_USER_STORAGE\",\r\n        \"reason\": \"用于读取本地文件进行分享\",\r\n        \"usedScene\": {\r\n            \"abilities\": [\"EntryAbility\"],\r\n            \"when\": \"inuse\"\r\n        }\r\n    },\r\n    {\r\n        \"name\": \"ohos.permission.WRITE_USER_STORAGE\",\r\n        \"reason\": \"用于临时存储分享文件\",\r\n        \"usedScene\": {\r\n            \"abilities\": [\"EntryAbility\"],\r\n            \"when\": \"inuse\"\r\n        }\r\n    }\r\n]\r\n```\r\n\r\n### 2. 邮件应用配置\r\n\r\n若需使用邮件分享功能，需在 module.json5 中配置邮件应用相关权限与能力，确保可正常拉起系统邮件应用：\r\n\r\n```json\r\n\"skills\": [\r\n    {\r\n        \"entities\": [\r\n            \"entity.system.mail\"\r\n        ],\r\n        \"actions\": [\r\n            \"ohos.want.action.SEND_MAIL\"\r\n        ]\r\n    }\r\n]\r\n```\r\n\r\n## 约束与限制\r\n\r\n- 依赖插件：无强制依赖插件，@cordova-ohos/ohos 版本为 2.0.0 及以上；\r\n\r\n- 平台限制：OHOS 平台依赖系统原生分享面板，分享功能的兼容性取决于系统版本及已安装的社交应用，建议适配 OHOS 5.0 及以上版本；\r\n\r\n- 邮件应用限制：OHOS 系统邮件应用需提前配置（如绑定邮箱账号），否则无法正常拉起或发送邮件；\r\n\r\n- 指定应用拉起限制：通过 URI 拉起指定应用时，需确保设备已安装该应用，且 URI 格式符合应用要求，否则拉起失败；\r\n\r\n- API 调用时机：所有 JavaScript API 必须在 `deviceready` 事件触发后调用，否则会出现 `window.plugins.socialsharing` 对象未定义、调用失败等异常；\r\n\r\n- 分享结果回调：OHOS 系统分享面板的回调结果仅能判断是否发起分享，无法准确判断分享是否成功（受系统分享机制限制）。\r\n\r\n### 兼容性\r\n\r\n支持：\r\n\r\n| 项目 | 版本/信息 |\r\n|-----|--------|\r\n| SDK | API12+ |\r\n| IDE | DevEco Studio: 5.0+ |\r\n| ROM | 5.1+ |\r\n| Emulator | OpenHarmony 6.0+ |\r\n\r\n在以下版本中已测试通过：\r\n\r\n| 项目 | 版本/信息 |\r\n|-----|--------|\r\n| @cordova-ohos/ohos | 14.0.1-ohos-14.0.1 |\r\n| SDK | 5.0.0(12) |\r\n| IDE | DevEco Studio: 6.0.13.200 |\r\n| ROM | 5.1.0.120 SP3 |\r\n| Emulator | OpenHarmony 6.0.1(21) |\r\n\r\n## 使用示例\r\n\r\n插件通过全局对象 `window.plugins.socialsharing` 暴露所有 API，支持回调函数与 Promise 两种调用方式（推荐使用 Promise 简化异步逻辑）。所有 API 需在 `deviceready` 事件触发后调用，以下为各核心功能的完整使用示例，可直接复制到项目中使用，重点注意 OHOS 平台的特性与限制。\r\n\r\n### 1. 检查分享插件是否存在\r\n\r\n检测插件是否成功集成并可用，用于初始化时的前置判断：\r\n\r\n```js\r\n// 等待 Cordova 环境就绪\r\ndocument.addEventListener('deviceready', function() {\r\n    window.plugins.socialsharing.available(function(){\r\n        console.log(\"分享插件存在，可正常使用\");\r\n    })\r\n}, false);\r\n```\r\n\r\n### 2. 核心分享 API（多场景示例）\r\n\r\n核心分享 API 支持文本、图片、链接等多种内容类型，可灵活组合配置，以下为不同场景的使用示例：\r\n\r\n```js\r\n// 等待 Cordova 环境就绪\r\ndocument.addEventListener('deviceready', function() {\r\n    // 1. 仅分享文本\r\n    window.plugins.socialsharing.share('这是仅分享的文本内容')\r\n    \r\n    // 2. 分享文本+主题\r\n    window.plugins.socialsharing.share('这是分享的文本', '这是分享的主题')\r\n    \r\n    // 3. 仅分享链接\r\n    window.plugins.socialsharing.share(null, null, null, 'http://www.example.com')\r\n    \r\n    // 4. 分享文本+主题+链接\r\n    window.plugins.socialsharing.share('这是带链接的文本', '分享主题', null, 'http://www.example.com')\r\n    \r\n    // 5. 仅分享在线图片\r\n    window.plugins.socialsharing.share(null, null, 'https://www.example.com/images/srpr/logo4w.png', null)\r\n    \r\n    // 6. 分享 base64 图片\r\n    window.plugins.socialsharing.share(null, null, 'data:image/png;base64,R0lGODlhDAAMALMBAP8AAP///wAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACH5BAUKAAEALAAAAAAMAAwAQAQZMMhJK7iY4p3nlZ8XgmNlnibXdVqolmhcRQA7', null)\r\n    \r\n    // 7. 分享文本+在线图片\r\n    window.plugins.socialsharing.share(\"这是带图片的分享\", null, 'https://www.example.com/images/srpr/logo4w.png', null)\r\n    \r\n    // 8. 分享文本+在线图片+链接\r\n    window.plugins.socialsharing.share(\"这是带图片和链接的分享\", null, 'https://www.example.com/images/srpr/logo4w.png', 'http://www.example.com')\r\n    \r\n    // 9. 分享沙箱路径图片\r\n    window.plugins.socialsharing.share(null, null, '/data/storage/el2/base/logo4w.png', null)\r\n    \r\n    // 10. 带回调的分享（获取分享结果）\r\n    window.plugins.socialsharing.share(\r\n        '带回调的分享文本',\r\n        '分享主题',\r\n        'https://www.example.com/images/srpr/logo4w.png',\r\n        'http://www.example.com',\r\n        null,\r\n        function(result){\r\n            console.log(\"分享结果:\" + result); // 仅能判断是否发起分享，无法确认是否成功\r\n        },\r\n        function(){\r\n            console.log(\"分享失败\");\r\n        }\r\n    )\r\n}, false);\r\n```\r\n\r\n### 3. 检查邮件应用是否可用\r\n\r\n检测 OHOS 系统自带邮件应用是否可用，用于邮件分享功能的前置判断：\r\n\r\n```js\r\n// 等待 Cordova 环境就绪\r\ndocument.addEventListener('deviceready', function() {\r\n    // OHOS 自带邮件系统可用性检测\r\n    window.plugins.socialsharing.canShareViaEmail(function(){\r\n        console.log(\"邮件应用支持，可正常使用\");\r\n    },function(){\r\n        console.log(\"邮件应用不支持或未配置\");\r\n    })\r\n}, false);\r\n```\r\n\r\n### 4. 拉起邮件应用发送邮件\r\n\r\n拉起 OHOS 系统邮件应用，支持发送带附件、抄送、密送的邮件，需提前配置邮件应用：\r\n\r\n```js\r\n// 等待 Cordova 环境就绪\r\ndocument.addEventListener('deviceready', function() {\r\n    window.plugins.socialsharing.shareViaEmail(\r\n        '这是邮件正文内容',\r\n        '这是邮件主题',\r\n        ['to@person1.com', 'to@person2.com'], // 收件人邮箱\r\n        ['cc@person1.com'], // 抄送邮箱\r\n        ['bcc@person1.com'], // 密送邮箱\r\n        ['https://cordova.apache.org/static/img/cordova_bot.png'], // 邮件附件（在线图片）\r\n        function(){\r\n            console.log(\"邮件应用拉起成功\");\r\n        },\r\n        function(){\r\n            console.log(\"邮件应用拉起失败\");\r\n        }\r\n    );\r\n}, false);\r\n```\r\n\r\n### 5. 拉起短信应用发送短信\r\n\r\n拉起 OHOS 系统短信应用，支持向多个号码发送短信：\r\n\r\n```js\r\n// 等待 Cordova 环境就绪\r\ndocument.addEventListener('deviceready', function() {\r\n    window.plugins.socialsharing.shareViaSMS(\r\n        {\r\n            message: \"这是短信内容\",\r\n            subject: \"短信主题\"\r\n        },\r\n        \"1390001111,13900002222\", // 接收短信的号码，多个号码用逗号分隔\r\n        function(){\r\n            console.log(\"短信应用拉起成功\");\r\n        },\r\n        function(){\r\n            console.log(\"短信应用拉起失败\");\r\n        }\r\n    )\r\n}, false);\r\n```\r\n\r\n### 6. 判断是否可以拉起指定应用\r\n\r\n通过应用 URI 判断设备是否已安装指定应用，用于定向分享或跳转的前置判断：\r\n\r\n```js\r\n// 等待 Cordova 环境就绪\r\ndocument.addEventListener('deviceready', function() {\r\n    // 判断是否可以拉起高德应用，传入高德应用的 URI\r\n    window.plugins.socialsharing.canShareVia(\r\n        \"amapuri://route/plan?sid=BGVIS1&dlat=39.98848272&dname=B&slat=39.92848272&dlon=116.47560823&did=BGVIS2&slon=116.39560823&sname=A&t=0&sourceApplication=applicationName\",\r\n        \"分享的文本消息\",\r\n        \"分享主题\",\r\n        null,\r\n        null,\r\n        function(){\r\n            console.log(\"可以拉起指定应用\");\r\n        },\r\n        function(){\r\n            console.log(\"不可拉起指定应用（未安装或 URI 错误）\");\r\n        }\r\n    )\r\n}, false);\r\n```\r\n\r\n### 7. 拉起指定应用\r\n\r\n通过应用 URI 拉起指定应用，可附带分享内容：\r\n\r\n```js\r\n// 等待 Cordova 环境就绪\r\ndocument.addEventListener('deviceready', function() {\r\n    // 拉起高德应用，传入高德应用的 URI 及分享内容\r\n    window.plugins.socialsharing.shareVia(\r\n        \"amapuri://route/plan?sid=BGVIS1&dlat=39.98848272&dname=B&slat=39.92848272&dlon=116.47560823&did=BGVIS2&slon=116.39560823&sname=A&t=0&sourceApplication=applicationName\",\r\n        \"这是分享给高德应用的文本\",\r\n        \"分享主题\",\r\n        null,\r\n        null,\r\n        function(){\r\n            document.getElementById(\"shareText\").innerHTML = \"拉起成功\";\r\n        },\r\n        function(){\r\n            document.getElementById(\"shareText\").innerHTML = \"拉起失败\";\r\n        }\r\n    )\r\n}, false);\r\n```\r\n\r\n## 使用说明\r\n\r\n以下为插件使用的核心说明，包括 API 详解、参数说明、常见问题及注意事项等，帮助开发者快速上手并避免异常，重点突出 OHOS 平台特性与限制。\r\n\r\n### 1. 核心 API 说明\r\n\r\n插件所有方法均挂载在 `window.plugins.socialsharing` 下，无需额外引入，支持回调函数与 Promise 两种调用方式，所有 API 均需在 `deviceready` 事件触发后调用。\r\n\r\n#### 1.1 检查插件是否可用\r\n\r\n功能：检测插件是否成功集成并可用，用于初始化时的前置判断。\r\n\r\n语法：\r\n\r\n```javascript\r\nwindow.plugins.socialsharing.available(successCallback);\r\n```\r\n\r\n参数说明：\r\n\r\n- successCallback：成功回调，无参数，触发即表示插件可用。\r\n\r\n#### 1.2 核心分享 API\r\n\r\n功能：实现文本、图片、链接、文件等内容的分享，支持多种组合配置，是插件最核心的 API。\r\n\r\n语法：\r\n\r\n```javascript\r\nwindow.plugins.socialsharing.share(message, subject, fileOrFileArray, url, iPadCoordinates, successCallback, errorCallback);\r\n```\r\n\r\n参数说明：\r\n\r\n- message：分享的文本内容，可选，为 null 时不分享文本；\r\n\r\n- subject：分享的主题，可选，仅部分应用（如邮件、短信）支持；\r\n\r\n- fileOrFileArray：分享的文件/图片，可选，可传入单个文件路径、在线图片地址、base64 图片，或多个文件组成的数组；\r\n\r\n- url：分享的网页链接，可选，为 null 时不分享链接；\r\n\r\n- iPadCoordinates：iPad 平台专用参数，OHOS 平台可传入 null；\r\n\r\n- successCallback：成功回调，参数为分享结果（仅能判断是否发起分享，无法确认是否成功）；\r\n\r\n- errorCallback：失败回调，无参数，触发即表示分享发起失败。\r\n\r\n#### 1.3 邮件应用可用性检测\r\n\r\n功能：检测 OHOS 系统自带邮件应用是否可用，用于邮件分享的前置判断。\r\n\r\n语法：\r\n\r\n```javascript\r\nwindow.plugins.socialsharing.canShareViaEmail(successCallback, errorCallback);\r\n```\r\n\r\n参数说明：\r\n\r\n- successCallback：成功回调，无参数，触发即表示邮件应用可用；\r\n\r\n- errorCallback：失败回调，无参数，触发即表示邮件应用不可用或未配置。\r\n\r\n#### 1.4 拉起邮件应用\r\n\r\n功能：拉起 OHOS 系统邮件应用，发送带正文、主题、附件、抄送、密送的邮件。\r\n\r\n语法：\r\n\r\n```javascript\r\nwindow.plugins.socialsharing.shareViaEmail(message, subject, to, cc, bcc, attachments, successCallback, errorCallback);\r\n```\r\n\r\n参数说明：\r\n\r\n- message：邮件正文内容，必填；\r\n\r\n- subject：邮件主题，必填；\r\n\r\n- to：收件人邮箱数组，必填，如 ['to1@example.com', 'to2@example.com']；\r\n\r\n- cc：抄送邮箱数组，可选，为 null 时不抄送；\r\n\r\n- bcc：密送邮箱数组，可选，为 null 时不密送；\r\n\r\n- attachments：邮件附件数组，可选，可传入在线文件地址或本地文件路径；\r\n\r\n- successCallback：成功回调，无参数，触发即表示邮件应用拉起成功；\r\n\r\n- errorCallback：失败回调，无参数，触发即表示邮件应用拉起失败。\r\n\r\n#### 1.5 拉起短信应用\r\n\r\n功能：拉起 OHOS 系统短信应用，向指定号码发送短信。\r\n\r\n语法：\r\n\r\n```javascript\r\nwindow.plugins.socialsharing.shareViaSMS(options, phoneNumbers, successCallback, errorCallback);\r\n```\r\n\r\n参数说明：\r\n\r\n- options：短信配置对象，包含 message（短信内容，必填）、subject（短信主题，可选）；\r\n\r\n- phoneNumbers：接收短信的号码，必填，多个号码用逗号分隔，如 \"1390001111,13900002222\"；\r\n\r\n- successCallback：成功回调，无参数，触发即表示短信应用拉起成功；\r\n\r\n- errorCallback：失败回调，无参数，触发即表示短信应用拉起失败。\r\n\r\n#### 1.6 判断是否可拉起指定应用\r\n\r\n功能：通过应用 URI 判断设备是否已安装指定应用，用于定向拉起的前置判断。\r\n\r\n语法：\r\n\r\n```javascript\r\nwindow.plugins.socialsharing.canShareVia(uri, message, subject, fileOrFileArray, url, successCallback, errorCallback);\r\n```\r\n\r\n参数说明：\r\n\r\n- uri：指定应用的 URI，必填；\r\n\r\n- message：分享的文本内容，可选，为 null 时不分享文本；\r\n\r\n- subject：分享的主题，可选；\r\n\r\n- fileOrFileArray：分享的文件/图片，可选；\r\n\r\n- url：分享的网页链接，可选；\r\n\r\n- successCallback：成功回调，无参数，触发即表示可拉起指定应用；\r\n\r\n- errorCallback：失败回调，无参数，触发即表示不可拉起指定应用。\r\n\r\n#### 1.7 拉起指定应用\r\n\r\n功能：通过应用 URI 拉起指定应用，并附带分享内容。\r\n\r\n语法：\r\n\r\n```javascript\r\nwindow.plugins.socialsharing.shareVia(uri, message, subject, fileOrFileArray, url, successCallback, errorCallback);\r\n```\r\n\r\n参数说明：与 1.6 中 `canShareVia` 方法一致，仅回调含义不同：\r\n\r\n- successCallback：成功回调，无参数，触发即表示指定应用拉起成功；\r\n\r\n- errorCallback：失败回调，无参数，触发即表示指定应用拉起失败。\r\n\r\n### 2. 常见问题（FAQ）\r\n\r\n#### Q1: 调用插件 API 后无反应怎么办？\r\n\r\n1. 检查 API 调用时机：确保在 `deviceready` 事件触发后调用，否则 `window.plugins.socialsharing` 对象可能未定义；\r\n\r\n2. 检查插件安装：执行 `hcordova plugin list` 确认插件已成功安装，若未安装则重新执行安装命令；\r\n\r\n3. 检查 OHOS 配置：若涉及本地文件分享或邮件分享，确认已完成权限配置和邮件应用配置；\r\n\r\n4. 检查设备权限：确保应用已获取文件访问权限（本地文件分享场景），可在系统设置中手动开启；\r\n\r\n5. 重新构建项目：执行 `hcordova build ohos`，确保插件资源和配置正确加载。\r\n\r\n#### Q2: 本地文件/沙箱图片分享失败怎么办？\r\n\r\n1. 检查文件路径：确保传入的文件路径正确，OHOS 沙箱路径需符合系统规范，避免路径错误；\r\n\r\n2. 检查文件权限：确认应用已申请 `READ_USER_STORAGE` 和 `WRITE_USER_STORAGE` 权限，未申请则添加权限配置并重新构建；\r\n\r\n3. 检查文件格式：确保分享的文件格式被目标应用支持，避免分享不兼容的文件类型。\r\n\r\n#### Q3: 邮件应用无法拉起或发送邮件怎么办？\r\n\r\n1. 检查邮件配置：确认 OHOS 系统邮件应用已绑定邮箱账号，可正常发送邮件；\r\n\r\n2. 检查权限配置：确认已在 module.json5 中配置邮件应用相关的 skills 和权限；\r\n\r\n3. 检查附件格式：确保邮件附件格式被邮件应用支持，避免传入过大或不兼容的附件。\r\n\r\n#### Q4: 无法拉起指定应用怎么办？\r\n\r\n1. 检查应用安装：确认设备已安装该指定应用，未安装则提示用户安装；\r\n\r\n2. 检查 URI 格式：确保传入的 URI 格式正确，符合该应用的 URI 规范（可参考应用官方文档）；\r\n\r\n3. 检查系统限制：部分 OHOS 系统版本可能限制第三方应用拉起三方应用，需适配系统版本。\r\n\r\n#### Q5: 分享回调显示成功，但实际未分享成功怎么办？\r\n\r\n该问题是 OHOS 系统原生分享面板的机制限制，插件无法解决。回调成功仅表示分享请求已发起，是否实际分享成功，取决于用户在分享面板中的操作（如取消分享），无法通过插件获取准确的分享结果。\r\n\r\n### 3. 注意事项\r\n\r\n- API 调用时机：所有 JavaScript API 必须在 `deviceready` 事件触发后调用，否则会出现对象未定义、调用失败等异常。\r\n\r\n- 权限配置：本地文件、沙箱图片分享需提前申请文件访问权限，邮件分享需配置邮件应用相关权限，否则会导致功能异常。\r\n\r\n- 路径规范：OHOS 平台本地文件路径需符合系统沙箱规范。\r\n\r\n- 分享结果：OHOS 系统分享面板的回调仅能判断分享请求是否发起，无法准确判断分享是否成功，需在应用中做好用户引导。\r\n\r\n- 应用兼容性：指定应用拉起功能依赖设备已安装该应用，且 URI 格式符合应用要求，不同应用的 URI 规范可能不同，需参考对应应用的官方文档。\r\n\r\n- 版本兼容性：确保 HCordova CLI、cordova-openharmony、OHOS 系统版本符合要求，避免因版本不兼容导致插件功能异常。\r\n\r\n- 文件大小限制：分享大文件（如大型视频、PDF）时，需注意系统和目标应用的文件大小限制，避免因文件过大导致分享失败。\r\n\r\n## 目录结构\r\n\r\n```\r\ncordova-plugin-x-socialsharing       # [根目录] 社交分享功能插件项目根目录\r\n├── src                              # [源码目录] 存放原生平台代码\r\n│   └── main                         # [主目录] 主代码目录\r\n│       ├── cpp                      # [C++ 目录] C++ 原生代码目录\r\n│       │   └── SocialSharing        # [C++ 模块] 社交分享功能 C++ 模块文件夹\r\n│       │       ├── SocialSharing.cpp # [C++ 实现] C++ 源文件，调用系统分享或第三方 SDK 实现分享逻辑\r\n│       │       └── SocialSharing.h   # [C++ 声明] C++ 头文件，定义分享接口\r\n│       └── ets                      # [ArkTS 目录] OHOS ArkTS/ETS 代码目录\r\n│           └── components           # [组件目录] 存放 UI 组件\r\n│               └── SocialSharing    # [TS 模块] 分享相关的 UI 组件文件夹\r\n│                   └── SocialSharing.ets # [ETS 文件] 分享面板、授权界面等 UI 组件\r\n├── www                              # [前端目录] 存放供 Web 端调用的 JS 接口文件\r\n│   └── SocialSharing.js             # [JS 文件] 暴露给 Web 端的 JS 接口\r\n├── LICENSE                          # [文本] 开源许可证文件\r\n├── .gitignore                       # [配置] Git 版本控制忽略文件配置\r\n├── OAT.xml                          # [配置] 门禁配置文件\r\n├── package.json                     # [配置] NPM 包配置文件，定义插件元数据\r\n├── plugin.xml                       # [配置] Cordova 插件核心配置文件，定义插件结构、依赖和映射关系\r\n└── README.md                        # [文档] 插件说明文档，包含安装、使用方法等\r\n```\r\n\r\n## 贡献代码\r\n\r\n使用过程中发现任何问题都可以提 [Issue](https://gitcode.com/CPF-Cordova/cordova-plugin-x-socialsharing/issues) ，当然也非常欢迎发 [PR](https://gitcode.com/CPF-Cordova/cordova-plugin-x-socialsharing/pulls) 共建。\r\n\r\n## 许可证\r\n\r\n本插件基于 **Apache License** 开源，详见 [LICENSE](LICENSE) 文件。\r\n\r\n\r\n## 官方资源\r\n\r\n- Android 和 iOS：[cordova-plugin-x-socialsharing 官方指南](https://www.npmjs.com/package/cordova-plugin-x-socialsharing)\r\n\r\n- GitCode 仓库：[https://gitcode.com/CPF-Cordova/cordova-plugin-x-socialsharing](https://gitcode.com/CPF-Cordova/cordova-plugin-x-socialsharing)\r\n","readmeFilename":"README.md"}