更新记录

1.1.2（2026-03-06）

一、fileName处理

1.1.1（2026-02-09）

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

1.1.0（2026-02-09）

一、iOS数据重复监听问题

平台兼容性

uni-app(4.0)

hl-share-uts

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

功能特性

• 双端标准支持：提供标准化的 API，简化 Android 与 iOS 跨平台开发逻辑。
• 多种分享模式：支持单文件、多图片、邮件（带附件）等多种分享方式。
• 指定应用分享：Android 侧支持直接通过包名唤起微信、QQ、钉钉、飞书进行精准分享。
• 接收分享内容：支持监听并解析其他应用分享到本应用的文件（支持冷启动、后台唤醒及安全范围资源访问）。

平台差异性说明

文件接收能力对比

分享功能对比

快速上手

1. 导入插件

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

2. 设置接收分享回调（只需这一处）

在 App 首页或全局脚本中仅需注册一次 onUpdateCallback。从微信、QQ 等分享文件进来时（含冷启动、后台被唤起），都会在该回调里收到数据；交付一次后会自动清空，不会重复触发。

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

    if (platform === 'android') {
      // Android: 支持单文件和多文件
      const files = result.data.data.files; // 数组或键 "0","1" 的对象
      const count = result.data.data.count; // 文件总数

      for (let i = 0; i < count; i++) {
        const file = files[i] ?? files[i.toString()];
        console.log('文件路径:', file.filePath);
        console.log('文件名:', file.fileName);
        console.log('MIME类型:', file.mimeType);
      }
    } else {
      // iOS: 仅支持单文件
      const fileInfo = result.data.fileInfo;
      console.log('文件路径:', fileInfo.filePath);
      console.log('文件名:', fileInfo.fileName);
      console.log('文件大小:', fileInfo.fileSize);
      console.log('文件类型:', fileInfo.fileType); // image/video/audio/document/archive/other
    }
  }
});

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,   // Android: 指定钉钉分享
  feishu: 0      // Android: 指定飞书分享
}, (result) => {
  // ...
});

接收数据结构说明

Android 平台 (result.data)

单文件示例：

{
  "data": {
    "files": [
      {
        "index": 0,
        "uri": "content://com.tencent.mm.external.fileprovider/...",
        "filePath": "/data/.../cache/shared_files/logo.png",
        "fileName": "logo.png",
        "mimeType": "image/png",
        "fileSize": 12345,
        "fileExtension": "png",
        "fileType": "image"
      }
    ],
    "count": 1
  }
}

多文件示例：（files 为数组，部分环境可能为键 "0","1" 的对象）

{
  "data": {
    "files": [
      { "index": 0, "uri": "...", "filePath": ".../shared_files/image1.jpg", "fileName": "image1.jpg", "mimeType": "image/jpeg", "fileSize": 0, "fileExtension": "jpg", "fileType": "image" },
      { "index": 1, "uri": "...", "filePath": ".../shared_files/image2.jpg", "fileName": "image2.jpg", "mimeType": "image/jpeg", "fileSize": 0, "fileExtension": "jpg", "fileType": "image" }
    ],
    "count": 2
  }
}

字段说明：

• index: 文件索引（从 0 开始）
• uri: 原始 Content URI（用于追溯来源）
• filePath: 本地绝对路径（已复制到应用私有目录 cache/shared_files/，可直接使用；保持原文件名，重名时加 " (1)" 等后缀）
• fileName: 原始文件名（插件不修改文件名前缀）
• mimeType: MIME 类型
• fileSize: 文件大小（字节）
• fileExtension: 文件扩展名
• fileType: 类型分类（image/video/audio/document/archive/other）
• count: 文件总数

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"
  }
}

字段说明：

• fileName: 文件名（含扩展名）
• filePath: 本地绝对路径（可直接使用）
• fileSize: 文件大小（字节）
• fileExtension: 文件扩展名（小写）
• mimeType: MIME 类型
• fileType: 文件类型分类，可能值：
  • image - 图片（jpg, png, gif, heic 等）
  • video - 视频（mp4, mov, avi 等）
  • audio - 音频（mp3, wav, aac 等）
  • document - 文档（pdf, doc, xls, ppt 等）
  • archive - 压缩包（zip, rar, 7z 等）
  • other - 其他类型

平台差异总结

注意事项

通用注意事项

1. 绝对路径：分享接口传入的路径必须是绝对路径，建议使用 plus.io.convertLocalFileSystemURL() 转换。

2. 回调时机：

   • Android: 分享操作完成后立即回调（可知是否成功）
   • iOS: 调起分享面板后立即回调（无法知道用户是否完成分享）

跨平台兼容性建议

// 处理接收数据的跨平台兼容写法
function handleSharedFiles(result) {
  const platform = uni.getSystemInfoSync().platform;

  if (platform === 'android') {
    const files = result.data.data.files;
    const count = result.data.data.count;
    const fileList = [];
    for (let i = 0; i < count; i++) {
      const file = files[i] ?? files[i.toString()];
      fileList.push({
        path: file.filePath,
        name: file.fileName,
        type: file.mimeType,
        size: file.fileSize ?? null
      });
    }
    return fileList;

  } else {
    // iOS: 仅单文件
    const fileInfo = result.data.fileInfo;
    return [{
      path: fileInfo.filePath,
      name: fileInfo.fileName,
      type: fileInfo.mimeType,
      size: fileInfo.fileSize
    }];
  }
}

// 使用示例
shareClient.onUpdateCallback((result) => {
  if (result.code === 200) {
    const files = handleSharedFiles(result);
    console.log('收到文件:', files);
    // 统一处理文件列表...
  }
});