更新记录

1.0.2（2026-01-16）

重要变更

iOS 端优化

• 移除多文件接收逻辑：iOS 端现仅支持单文件接收（系统限制），移除了 handleMultipleURLContexts 方法
• 降低系统版本要求：iOS 最低支持版本从 13.0 降至 12.0，覆盖更多设备
• 修复打包签名问题：移除 Info.plist 中的 Bundle ID 等应用级配置，解决导出 IPA 时 Provisioning Profile 错误
• 优化配置文件：精简 Info.plist，仅保留必要的文件类型和 URL Scheme 配置

文档完善

• 新增平台差异说明：添加 Android 和 iOS 功能对比表
• 详细数据结构说明：补充单文件和多文件接收的完整示例
• 增强配置指南：分平台详细说明配置步骤和注意事项
• 新增跨平台兼容示例：提供统一处理两端数据的代码模板

功能特性

平台能力对比

问题修复

• [iOS] 修复导出 IPA 时提示 "requires a provisioning profile" 错误
• [iOS] 移除不必要的 Scene Delegate 相关代码
• [iOS] 修复 Info.plist 配置冲突导致的签名问题

注意事项

• iOS 平台限制：由于系统限制，iOS 端仅支持接收单个文件，Android 端支持多文件
• 配置简化：iOS 插件不再需要单独配置 Bundle ID，会自动继承主应用配置
• 无需 App Groups：本插件不使用 Share Extension，无需配置 App Groups 权限

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') {
      // 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.toString()];
        console.log('文件路径:', file.path);
        console.log('文件名:', file.displayName);
        console.log('MIME类型:', file.mime_type);
      }
    } 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) => {
  // ...
});

平台差异说明：

5. 主动检查分享内容 handleSharedContent

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

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

接收数据结构说明

Android 平台 (result.data)

单文件示例：

{
  "data": {
    "files": {
      "0": {
        "index": 0,
        "uri": "content://com.tencent.mm.external.fileprovider/...",
        "path": "/storage/emulated/0/Android/data/.../cache/hlshare/logo.png",
        "displayName": "logo.png",
        "mime_type": "image/png"
      }
    },
    "count": 1
  }
}

多文件示例：

{
  "data": {
    "files": {
      "0": {
        "index": 0,
        "uri": "content://...",
        "path": "/storage/.../cache/hlshare/image1.jpg",
        "displayName": "image1.jpg",
        "mime_type": "image/jpeg"
      },
      "1": {
        "index": 1,
        "uri": "content://...",
        "path": "/storage/.../cache/hlshare/image2.jpg",
        "displayName": "image2.jpg",
        "mime_type": "image/jpeg"
      },
      "2": {
        "index": 2,
        "uri": "content://...",
        "path": "/storage/.../cache/hlshare/document.pdf",
        "displayName": "document.pdf",
        "mime_type": "application/pdf"
      }
    },
    "count": 3
  }
}

字段说明：

• index: 文件索引（从 0 开始）
• uri: 原始 Content URI（用于追溯来源）
• path: 本地绝对路径（已复制到应用私有目录，可直接使用）
• displayName: 文件显示名称
• mime_type: MIME 类型
• 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 - 其他类型

平台差异总结

平台配置指南

Android 配置

1. AndroidManifest.xml 配置

需在 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>

2. 文件类型过滤（可选）

如果只想接收特定类型的文件，可以修改 mimeType：

<!-- 仅接收图片 -->
<data android:mimeType="image/*" />

<!-- 仅接收视频 -->
<data android:mimeType="video/*" />

<!-- 仅接收 PDF -->
<data android:mimeType="application/pdf" />

3. 无需额外权限

插件会自动处理以下内容：

• ✅ Content URI 临时读取权限
• ✅ 文件复制到应用私有目录（cache/hlshare/）
• ✅ 文件名冲突处理（自动重命名）

iOS 配置

1. 文件类型支持

插件已在 Info.plist 中预配置了常见文件类型，支持：

• 图片: jpg, png, gif, heic, webp 等
• 文档: pdf, doc, docx, xls, xlsx 等
• 压缩包: zip, rar, 7z 等
• 音视频: mp3, mp4, mov, wav 等

2. 必需配置项（已内置）

以下配置已包含在插件中，无需手动添加：

<!-- Info.plist 已包含 -->
<key>LSSupportsOpeningDocumentsInPlace</key>
<true/>

<key>UIFileSharingEnabled</key>
<true/>

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>hlshare</string>
        </array>
    </dict>
</array>

3. 系统版本要求

• 最低支持: iOS 12.0
• 推荐版本: iOS 13.0+（更好的兼容性）

4. 限制说明

• ❌ 不支持多文件接收：iOS 系统限制，只能接收单个文件
• ❌ 不支持指定应用分享：只能调起系统分享面板
• ✅ 支持 Security-Scoped Resource：自动处理文件访问权限

配置对比

注意事项

通用注意事项

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

2. 冷启动处理：插件内部已处理冷启动逻辑，只要在 App 启动时及时注册 onUpdateCallback 即可收到内容。

3. 清理缓存：接收到的文件会暂存在应用的 cache 目录下，建议定期清理以节省空间。

4. 回调时机：

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

Android 特定注意事项

1. 权限自动处理：插件会自动处理 content:// URI 的临时读取权限并复制到应用私有目录，开发者无需额外处理权限申请。

2. 多文件接收：支持同时接收多个文件，数据结构为对象格式 {"0": {...}, "1": {...}}。

3. 指定应用分享：可通过 wx/qq/dingtalk/feishu 参数直接打开对应应用，需确保目标应用已安装。

4. 文件存储位置：接收的文件会复制到 {应用目录}/cache/hlshare/ 下。

5. 包名对应关系：

   • 微信：com.tencent.mm
   • QQ：com.tencent.mobileqq
   • 钉钉：com.alibaba.android.rimet
   • 飞书：com.ss.android.lark

iOS 特定注意事项

1. 单文件限制：由于 iOS 系统限制，仅支持接收单个文件，无法同时接收多个文件。

2. 系统分享面板：所有分享操作都会调起 iOS 系统分享面板，无法直接打开特定应用（wx/qq 等参数会被忽略）。

3. 文件访问权限：插件会自动处理 Security-Scoped Resource 访问，开发者无需关心 startAccessingSecurityScopedResource。

4. 文件存储位置：接收的文件默认存储在 tmp/ 临时目录，系统可能随时清理。

5. 文件类型识别：提供额外的 fileType 字段（image/video/audio/document/archive/other），方便业务层分类处理。

6. Bundle ID 配置：插件不包含独立的 Bundle ID 配置，会自动继承主应用配置，无需担心签名问题。

跨平台兼容性建议

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

  if (platform === 'android') {
    // 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.toString()];
      fileList.push({
        path: file.path,
        name: file.displayName,
        type: file.mime_type,
        size: null // Android 不提供大小
      });
    }
    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);
    // 统一处理文件列表...
  }
});