更新记录

1.0.1（2025-12-21）

一，首次提交

1.0.0（2025-12-21）

一、首次提交

平台兼容性

uni-app(4.0)

hl-share-uts

文件分享与接收 UTS 插件。支持将文件分享到第三方应用（微信、QQ、钉钉、飞书等），并支持处理从其他应用分享到本应用的文件内容。

功能特性

• 双端标准支持：提供标准化的 API，简化 Android 与 iOS 跨平台开发逻辑。
• 多种分享模式：支持单文件、多图片、邮件（带附件）等多种分享方式。
• 指定应用分享：Android 侧支持直接通过包名唤起微信、QQ、钉钉、飞书进行精准分享。
• 接收分享内容：支持监听并解析其他应用分享到本应用的文件（支持冷启动、后台唤醒及安全范围资源访问）。
• 文件自动处理：Android 侧自动解决 content:// 权限问题并复制到应用私有目录，确保 JS 层可访问；iOS 侧自动处理 Security-Scoped 资源访问。

快速上手

1. 导入插件

import { getHlShareClient } from '@/uni_modules/hl-share-uts';
const shareClient = getHlShareClient();

2. 设置实时接收监听

建议在 App 首页或全局脚本中设置监听，以确保捕获从外部分享进来的内容。

// 推荐在 App.vue 或首页 onLoad 中调用
shareClient.onUpdateCallback((result) => {
  if (result.code === 200) {
    console.log('收到分享内容:', result.data);
    const platform = uni.getSystemInfoSync().platform;

    if (platform === 'android') {
      const files = result.data.data.files; // Android 结构
      // 处理文件...
  } else {
      const fileInfo = result.data.fileInfo; // iOS 结构
      // 处理文件...
    }
  }
});

API 说明

1. 分享单个文件 shareFile

唤起系统分享选择器分享单个本地文件。

const filePath = plus.io.convertLocalFileSystemURL('_www/static/logo.png');
shareClient.shareFile(filePath, (result) => {
  if (result.code === 200) {
    uni.showToast({ title: '分享成功' });
  }
});

2. 分享多张图片 shareMultipleImages

唤起系统分享选择器批量分享图片。

const imagePaths = [
  plus.io.convertLocalFileSystemURL('_www/static/image1.png'),
  plus.io.convertLocalFileSystemURL('_www/static/image2.png')
];
shareClient.shareMultipleImages(imagePaths, (result) => {
  // ...
});

3. 邮件分享 sharetoMail

唤起系统邮件客户端并填充内容。

shareClient.sharetoMail({
  path: [filePath], // 附件路径数组
  title: '邮件主题',
  body: '邮件正文内容',
  tos: 'service@example.com', // 收件人
  tip: '请选择邮件应用'        // Android 专用：选择器提示语
}, (result) => {
  // ...
});

4. 通用分享/指定 App 分享 share

在 Android 上可尝试直接打开对应 App，iOS 则调起系统分享面板。

shareClient.share({
  path: [filePath],
  type: 'image', // 类型可选：image, video, audio, pdf, zip, other
  wx: 1,         // Android: 指定微信分享 (1-是, 0-否)
  qq: 0,         // Android: 指定 QQ 分享
  dingtalk: 0,
  feishu: 0
}, (result) => {
  // ...
});

5. 主动检查分享内容 handleSharedContent

用于手动触发一次当前接收到的内容处理。建议在页面 onShow 中调用以处理可能的遗漏。

shareClient.handleSharedContent((result) => {
  if (result.code === 200 && result.data) {
    // 成功获取数据
  }
});

接收数据结构说明

Android 平台 (result.data)

{
  "data": {
    "files": {
      "0": {
        "index": 0,
        "uri": "content://...",
        "path": "/storage/emulated/0/Android/data/.../cache/hlshare/logo.png", // 本地真实路径
        "displayName": "logo.png",
        "mime_type": "image/png"
      }
    },
    "count": 1
  }
}

iOS 平台 (result.data)

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

平台配置指南

Android 配置

需在 AndroidManifest.xml 中配置 intent-filter 以允许应用出现在分享列表中。建议配置在 io.dcloud.PandoraEntry 活动下。

<activity android:name="io.dcloud.PandoraEntry" ...>
    <!-- 支持外部文件打开 -->
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:scheme="content" />
        <data android:mimeType="*/*" />
    </intent-filter>
    <!-- 支持接收单文件分享 -->
    <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="*/*" />
    </intent-filter>
    <!-- 支持接收多文件分享 -->
    <intent-filter>
        <action android:name="android.intent.action.SEND_MULTIPLE" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="*/*" />
    </intent-filter>
</activity>

iOS 配置

1. 文件类型支持：在 manifest.json -> App常用其它设置 -> iOS设置 -> CFBundleDocumentTypes 中配置支持的 UTI。
2. 原地打开支持：设置 LSSupportsOpeningDocumentsInPlace 为 true。
3. URL Scheme：如需支持 Scheme 唤起，请在 URL Types 中添加 hlshare。

注意事项

1. 绝对路径：分享接口传入的路径必须是绝对路径。
2. 权限处理：Android 侧插件会自动处理 content:// URI 的临时读取权限并拷贝到应用目录，开发者无需额外处理权限申请。
3. 冷启动处理：插件内部已处理冷启动逻辑，只要在 App 启动时及时注册 onUpdateCallback 即可收到内容。
4. 清理缓存：接收到的文件会暂存在应用的 cache 目录下，建议定期清理以节省空间。