更新记录

1.1.0（2026-06-01）

• 新增 setFileOpenConfig API，支持配置 includeBase64（默认 true，保持兼容），大文件可关闭 base64 避免内存占用和闪屏
• 新增 clearSharedFileCache API，清空分享文件缓存目录
• 新增 clearSharedFile API，按路径删除单个缓存文件（含路径安全校验）

1.0.2（2026-05-23）

• 修复 Android 部分应用通过 ClipData 传递文件 URI 时无法接收的问题
• 修复 Android file:// 路径文件复制失败导致无回调的问题
• 修复 Android 监听注册前到达的 Intent 被丢弃的问题（对齐 iOS pending 机制）
• 优化 Intent 去重逻辑，避免重复触发回调

1.0.0（2026-03-11）

初始版发布

平台兼容性

uni-app(4.84)

uni-app x(4.84)

jun-file-open

文件分享接收插件，让其他应用可以通过"分享"或"打开方式"或"用其他应用打开"或"共享"将文件发送到本应用。

功能

• 用其他应用打开文件时，可在分享列表中看到本应用
• 接收分享的文件并获取文件路径、文件名、MIME类型、文件大小、扩展名等信息
• 支持单文件和多文件分享
• 支持 PDF、Office文档、图片、视频、音频、文本、压缩包等各类文件
• iOS 和 Android 双平台支持
• 可配置是否返回 base64 数据（大文件性能优化）
• 提供缓存清理 API，避免存储占用持续增长

支持的文件类型

默认支持以下文件类型（可通过修改 AndroidManifest.xml 和 Info.plist 自定义）：

使用方法

1. 注册监听

在 App.vue 的 onLaunch 中尽早注册（不要包在 #ifdef APP-ANDROID 里，否则可能被条件编译剔除）：

import {
  setFileOpenConfig,
  onFileShared,
  offFileShared,
  checkSharedFile,
  clearSharedFileCache,
  clearSharedFile,
} from "@/uni_modules/jun-file-open";

// 大文件场景建议关闭 base64，避免内存占用和闪屏（默认 true，保持兼容）
setFileOpenConfig({ includeBase64: false });

function handleSharedFile(res) {
  console.log("收到分享文件：", res.files);
  // 处理完成后清理缓存
  res.files.forEach((file) => {
    clearSharedFile(file.filePath);
  });
  // 或一次性清空全部：clearSharedFileCache();
}

export default {
  onLaunch() {
    onFileShared(handleSharedFile);

    // Android 建议：监听 newintent，处理 App 已在后台时再次「打开方式/分享」
    // #ifdef APP-PLUS
    plus.globalEvent.addEventListener("newintent", () => {
      checkSharedFile(handleSharedFile);
    });
    // #endif
  },
  onExit() {
    offFileShared();
  },
};

iOS 端通过 plus.io 读取文件

iOS 端返回的 filePath 为 _doc/ 开头的相对路径（如 _doc/jun_file_open_shared/xxx.jpeg），可通过 plus.io.resolveLocalFileSystemURL 读取文件内容：

onFileShared((res) => {
  res.files.forEach((file) => {
    // 方式一：小文件可直接使用 base64Data（需 setFileOpenConfig({ includeBase64: true })，默认已开启）
    const base64 = file.base64Data;

    // 方式二：通过 plus.io 读取文件（大文件推荐，需 includeBase64: false）
    plus.io.resolveLocalFileSystemURL(
      file.filePath,
      (entry) => {
        entry.file((f) => {
          const reader = new plus.io.FileReader();
          reader.onloadend = (e) => {
            const dataUrl = e.target.result; // data:image/jpeg;base64,...
            console.log("读取成功，长度：", dataUrl.length);
          };
          reader.readAsDataURL(f);
        });
      },
      (err) => {
        console.error("解析路径失败：", err.message);
      },
    );
  });
});

注意：Android 端返回的 filePath 为 file:// 开头的绝对路径，iOS 端返回的为 _doc/ 开头的相对路径。小文件可使用 base64Data；大文件建议 setFileOpenConfig({ includeBase64: false }) 后通过 filePath 读取。

2. 取消监听

在不需要时取消监听：

offFileShared();

3. 手动检查

主动检查当前是否有待处理的分享文件：

import { checkSharedFile } from "@/uni_modules/jun-file-open";

checkSharedFile((res) => {
  console.log("检查到分享文件：", res.files);
});

4. 清理缓存

分享文件会被复制到插件缓存目录，使用完毕后请调用清理 API：

import { clearSharedFileCache, clearSharedFile } from "@/uni_modules/jun-file-open";

// 清空全部缓存，返回 { deletedCount: number }
const result = clearSharedFileCache();
console.log("已删除文件数：", result.deletedCount);

// 删除单个文件（Android: file:// 路径；iOS: _doc/ 相对路径）
clearSharedFile(file.filePath);

API

setFileOpenConfig(config)

设置插件全局配置，建议在 onFileShared 之前调用。

参数：

• config.includeBase64: boolean - 是否在回调中包含 base64Data，默认 true。大文件建议设为 false，通过 filePath 读取以避免内存占用和闪屏。

setFileOpenConfig({ includeBase64: false });

onFileShared(callback)

注册文件分享接收监听。当其他应用分享文件到本应用时，callback 会被调用。

参数：

• callback: (res: SharedFileResult) => void - 接收到文件时的回调

SharedFileResult：

• files: SharedFileInfo[] - 接收到的文件列表

SharedFileInfo：

• filePath: string - 文件本地缓存路径（Android 为 file:// 绝对路径，iOS 为 _doc/ 相对路径）
• fileName: string - 文件名
• mimeType: string - 文件MIME类型
• fileSize: number - 文件大小（字节）
• fileExtension: string - 文件扩展名
• base64Data: string - 文件内容的 base64 编码（includeBase64: true 时返回，否则为空字符串；读取失败时也为空字符串）

offFileShared()

取消文件分享接收监听。

checkSharedFile(callback)

手动检查当前是否有待处理的分享文件。

clearSharedFileCache()

清空分享文件缓存目录（jun_file_open_shared），返回 ClearSharedCacheResult：

• deletedCount: number - 删除的文件数量

clearSharedFile(filePath)

删除单个分享缓存文件。

参数：

• filePath: string - Android 为 file:// 绝对路径，iOS 为 _doc/jun_file_open_shared/... 相对路径

返回值： boolean - 是否删除成功（路径不在缓存目录内时返回 false）

自定义支持的文件类型

Android

修改 utssdk/app-android/AndroidManifest.xml 中的 <intent-filter> 的 <data android:mimeType="..." /> 来控制支持的文件类型。

iOS

修改 utssdk/app-ios/Info.plist 中的 CFBundleDocumentTypes 的 LSItemContentTypes 来控制支持的文件类型。

平台差异

注意事项

1. 需要自定义基座/云打包后才能生效（修改 Manifest 或 Info.plist 后需重新制作自定义基座）
2. 文件会被复制到插件缓存目录，使用完毕后请调用 clearSharedFileCache() 或 clearSharedFile() 清理
3. Android 端通过 Intent Filter 实现，iOS 端通过 Document Types + UTSiOSHookProxy 实现
4. 小文件可使用 base64Data；大文件建议 setFileOpenConfig({ includeBase64: false }) 后通过 filePath 读取，避免内存占用和闪屏
5. iOS 端的 filePath 为 _doc/ 开头的相对路径，可通过 plus.io.resolveLocalFileSystemURL 读取；Android 端为 file:// 绝对路径
6. Android 集成要点：onFileShared 必须在 App.vue 的 onLaunch 中调用；App 已在后台时再次打开文件，需监听 plus.globalEvent 的 newintent 并调用 checkSharedFile
7. 已知限制：微信等部分 App 的「用其他应用打开」可能不走标准 Android Intent，系统文件管理器、相册、WPS 等标准分享/打开方式可正常使用