更新记录

1.1.3（2026-04-10）

一、新增鸿蒙的主动分享文件、邮件分享的支持

1.1.2（2026-03-06）

一、fileName处理

1.1.1（2026-02-09）

一、接收文件处理逻辑优化

平台兼容性

uni-app(4.0)

hl-share-uts

文件分享 UTS 插件。

当前版本的定位是：

• Android：支持主动分享，也支持接收其他应用分享进来的文件
• iOS：支持主动分享；接收外部分享时同时兼容“直接打开文件”和“Share Extension 回传”
• HarmonyOS：仅支持主动分享，不支持接收其他应用分享进来的文件

功能概览

• 单文件分享
• 多图片分享
• 邮件分享
• Android 指定应用分享
• Android / iOS 外部分享接收
• Harmony 系统分享面板分享

平台差异

说明：

• HarmonyOS 当前版本只保留主动分享能力。
• iOS 直接“打开到 App / 文件打开”继续沿用现有 URL / fileURL 接收逻辑。
• iOS 如果希望在系统分享面板中出现当前应用，需要宿主额外创建 Share Extension，并通过 App Groups 把文件信息回传给主应用。
• 当前插件已经补上主应用侧读取 App Groups 共享文件的逻辑，不会影响原来的 iOS 接收方式。
• HarmonyOS 侧仍保留统一 API 形状，但不再实现接收外部分享的宿主入口与回调链路。
• 如果页面在 Harmony 上调用 handleSharedContent，会收到“不支持外部接收”的结果。

快速上手

1. 导入插件

import { getHlShareClient } from '@/uni_modules/hl-share-uts'

const shareClient = getHlShareClient()

2. 分享单个文件

const filePath = plus.io.convertLocalFileSystemURL('_www/static/logo.png')

shareClient.shareFile(filePath, (result) => {
  console.log(result)
})

3. 分享多张图片

const imagePaths = [
  plus.io.convertLocalFileSystemURL('_www/static/image1.png'),
  plus.io.convertLocalFileSystemURL('_www/static/image2.png')
]

shareClient.shareMultipleImages(imagePaths, (result) => {
  console.log(result)
})

4. 邮件分享

shareClient.sharetoMail({
  path: [filePath],
  title: '邮件主题',
  body: '邮件正文内容',
  tos: 'service@example.com',
  tip: '请选择邮件应用'
}, (result) => {
  console.log(result)
})

说明：

• Android 会尽量调起邮件相关能力
• iOS 会走系统分享面板
• Harmony 会把主题 / 正文 / 收件人整理为文本后走系统分享面板

5. 通用分享

shareClient.share({
  path: [filePath],
  type: 'image',
  wx: 1,
  qq: 0,
  dingtalk: 0,
  feishu: 0
}, (result) => {
  console.log(result)
})

说明：

• Android 支持尝试直接分享至指定应用
• iOS 不支持直接指定应用，实际仍是系统分享面板
• Harmony 当前统一回退到系统分享面板，wx / qq / dingtalk / feishu 仅作为目标提示

外部分享接收

Android

推荐在 App.vue 或首页 onShow 中注册 onUpdateCallback：

shareClient.onUpdateCallback((result) => {
  if (result.code !== 200) {
    return
  }

  console.log('收到分享内容:', result.data)
})

如需兼容旧页面逻辑，也可以主动调用：

shareClient.handleSharedContent((result) => {
  console.log(result)
})

iOS

iOS 当前支持两条接收链路：

1. “打开到 App / 文件打开”这类系统或应用直接传入 fileURL
2. 系统分享面板通过 Share Extension 把文件写入 App Groups，主应用在启动或回前台时读取

推荐在 App.vue 或首页 onShow 中注册 onUpdateCallback：

shareClient.onUpdateCallback((result) => {
  if (result.code !== 200) {
    return
  }

  console.log('收到分享内容:', result.data)
})

如需兼容旧页面逻辑，也可以主动调用：

shareClient.handleSharedContent((result) => {
  console.log(result)
})

iOS 系统分享面板的宿主要求：

• 需要在 Xcode 中创建 Share Extension Target
• 主应用和 Share Extension 需要配置同一个 App Groups
• Share Extension 需要把待分享文件写入共享容器，或把文件路径 / URL 写入共享 UserDefaults
• 主应用会在启动、回前台、激活、注册 onUpdateCallback 时自动检查共享数据

当前插件已兼容以下共享 UserDefaults key：

• shared_files / hl_share_shared_files / hlshare_shared_files
• shared_file / hl_share_shared_file / hlshare_shared_file
• shared_file_url / hl_share_file_url / hlshare_file_url
• shared_file_urls / hl_share_file_urls / hlshare_file_urls

其中值可以是：

• 文件 URL 字符串，如 file:///private/var/.../demo.pdf
• 文件绝对路径字符串
• 字典对象，支持 fileURL、url、filePath、path

App Groups 标识读取顺序如下：

• Info.plist 的 HLShareAppGroupIdentifiers
• Info.plist 的 HLShareAppGroupIdentifier
• 自动推导的 group.<bundleId>.hlshare
• 自动推导的 group.<bundleId>

HarmonyOS

HarmonyOS 当前版本不支持接收其他应用分享进来的文件：

• onUpdateCallback 保留为兼容接口，但不会收到外部分享回调
• handleSharedContent 会返回“当前平台不支持接收外部分享内容”
• 当前插件也不再提供 Harmony 宿主侧 ShareExtensionAbility 或 EntryAbility.skills 接收配置

接收数据结构

以下数据结构仅适用于 Android / iOS。

Android

Android 当前按多文件结构返回：

{
  "data": {
    "files": [
      {
        "index": 0,
        "uri": "content://... 或 file://...",
        "filePath": "/data/.../shared_files/demo.png",
        "fileName": "demo.png",
        "mimeType": "image/png",
        "fileSize": 12345,
        "fileExtension": "png",
        "fileType": "image"
      }
    ],
    "count": 1
  }
}

iOS

{
  "fileInfo": {
    "fileName": "logo.png",
    "filePath": "/private/var/mobile/Containers/Data/Application/.../tmp/logo.png",
    "fileSize": 12345,
    "fileExtension": "png",
    "mimeType": "image/png",
    "fileType": "image"
  }
}

说明：

• iOS 当前仍按单文件结构回传，保持现有业务字段不变。
• 即使 Share Extension 侧收到多个文件，主应用当前也只会消费第一条有效文件记录。

HarmonyOS 说明

HarmonyOS 当前实现聚焦在主动分享：

1. 支持单文件、多图、邮件降级分享，以及通用系统分享面板。
2. 不支持被其他应用通过系统分享面板拉起并传入文件。