更新记录

1.0.0（2026-09-07） 下载此版本

首发版本。

功能

• 接收其他应用通过「分享 / 用其他应用打开」发送的文件，支持单文件 / 多文件
• 支持 PDF、Office、图片、视频、音频、文本、压缩包等常见类型（文件类型可通过 Manifest / Info.plist 自定义）
• Android + iOS 双平台
• 回调返回 SharedFileInfo：filePath / fileName / mimeType / fileSize / fileExtension / base64Data
• 可配置是否返回 base64（setFileOpenConfig，大文件建议关闭）
• iOS 支持 pathMode（relative / absolute）返回不同形式的 filePath
• 提供缓存目录查询、单文件清理、缓存清空 API

修复与优化

• iOS：同一次「用其他应用打开」被系统/微信重复回调 openURL 时，按来源 URL 增加 1.5s 短时间去重，仅首次落盘分发，避免同一文件重复拷贝（app-ios/FileOpenHelper.swift）
• iOS：不实现已废弃的 applicationHandleOpenURL，仅接收 iOS 9+ 的 application:open:options 新回调，避免同一 openURL 事件被宿主双路径重复转发
• Android：处理 getParcelableArrayListExtra 的 deprecation 告警（沿用旧 API 以兼容 minSdk 19，@Suppress 抑制编译告警，app-android/FileOpenHelper.kt）
• Android：避免 AndroidManifest.xml 注释中出现连续双连字符，兼容云打包时的 simplexml 解析

文档

• 使用示例与已知限制中说明 uni-app（vue）工程 APP-ANDROID/APP-IOS 条件编译仅对 .uts 生效，并给出运行时平台判断写法
• 提供 Android 与 iOS 各自「读取文件」示例

平台兼容性

uni-app(5.24)

uni-app x(5.24)

lucis-share-receive

• 文件分享接收 UTS 插件：让其他应用可以通过「分享 / 打开方式 / 用其他应用打开 / 共享」将文件发送到本应用。

• 接收分享文件并获取：路径、文件名、MIME 类型、文件大小、扩展名

• 支持单文件 / 多文件分享

• 支持 PDF、Office、图片、视频、音频、文本、压缩包等

• Android + iOS 双平台

• 可配置是否返回 base64（大文件建议关闭）

• 提供缓存清理 API

平台差异

使用

1. 注册监听（App.vue onLaunch）

import {
  setFileOpenConfig,
  onFileShared,
  offFileShared,
  checkSharedFile,
  clearSharedFileCache,
  clearSharedFile,
} from "@/uni_modules/lucis-share-receive";

// includeBase64 默认关闭；开启时会把整个文件读入内存做 base64 编码，
// 大文件内存占用高（甚至 OOM），仅小文件或确有需要时开启
// pathMode：iOS 返回 filePath 的形式，'relative'(默认，_doc/...) 或 'absolute'(沙盒绝对路径)
setFileOpenConfig({ includeBase64: false, pathMode: "relative" });

function handleSharedFile(res) {
  console.log("收到分享文件：", res.files);
  res.files.forEach((file) => {
    clearSharedFile(file.filePath);
  });
}

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

    // Android：App 运行/在后台时再次被「打开方式/分享」唤起，系统走 onNewIntent，
    // 需监听 newintent 后主动 checkSharedFile 消费新 Intent
    // uni-app（vue）中 APP-ANDROID 条件编译仅对 .uts 生效，Android 判断请用运行时 platform
    // #ifdef APP-PLUS
    if (uni.getSystemInfoSync().platform === "android") {
      plus.globalEvent.addEventListener("newintent", () => {
        checkSharedFile(handleSharedFile);
      });
    }
    // #endif
  },
  onExit() {
    offFileShared();
  },
};

iOS 读取文件（按 pathMode 分支）：

onFileShared((res) => {
  res.files.forEach((file) => {
    const base64 = file.base64Data; // includeBase64: true 时可用

    // pathMode: "absolute" 时 filePath 是沙盒绝对路径，可直接交给原生 ffmpeg/ffprobe
    // ffmpegGetMediaInfo({ path: file.filePath, ... });

    // pathMode: "relative"(默认) 时 filePath 是 _doc/...，plus.io 可直接读写：
    const fileUrl = plus.io.convertLocalFileSystemURL(file.filePath);
    console.log("绝对路径:", fileUrl); // file:///var/mobile/.../Documents/Pandora/apps/<key>/doc/file_share_receive_shared/xx

    // 交给原生 ffmpeg 前先转绝对路径（去掉 file://）
    plus.io.resolveLocalFileSystemURL(file.filePath, (entry) => {
      // entry 为文件对象，可读/复制/上传
    });
  });
});

Android 读取文件（filePath 为 file:// 绝对路径）：

onFileShared((res) => {
  res.files.forEach((file) => {
    // 去掉 file:// 前缀即真实路径，可直接交给原生 ffmpeg/ffprobe 或 uni.openDocument
    const realPath = file.filePath.replace(/^file:\/\//, "");
    uni.openDocument({ filePath: realPath, showMenu: true });
  });
});

2. API

SharedFileInfo 字段：filePath / fileName / mimeType / fileSize / fileExtension / base64Data。

自定义支持的文件类型

• Android：修改 utssdk/app-android/AndroidManifest.xml 中 <data android:mimeType="..." />
• iOS：修改 utssdk/app-ios/Info.plist 中 CFBundleDocumentTypes 的 LSItemContentTypes

修改 Manifest / Info.plist 后必须重新制作自定义基座 / 云打包才能生效。

已知限制

• 微信等部分 App 的「用其他应用打开」可能不走标准 Android Intent；系统文件管理器、相册、WPS 等标准分享/打开方式可正常使用
• iOS 端使用 UTSiOSHookProxy 接收 openURL，仅支持 iOS 9+ 的 application:open:options 新回调；不实现已废弃的 applicationHandleOpenURL（iOS 9 前旧 API），避免同一 openURL 事件被宿主双路径重复转发。因此最低支持 iOS 9（uni-app 最低支持版本之上不受影响）
• iOS 系统/微信对同一次「用其他应用打开」可能重复回调多次 openURL，插件按来源 URL 做了 1.5s 短时间去重，仅首次落盘分发
• iOS 多文件分享在系统侧可能按多次单文件回调，需在 macOS 云打包后真机验证
• Android 端 onFileShared 需在 App.vue 的 onLaunch 中尽早调用；冷启动/首次注册会自动消费一次启动 Intent。App 已运行（前台/后台）再次被「打开方式/分享」唤起时走 onNewIntent，需监听 plus.globalEvent 的 newintent 并调用 checkSharedFile()；该事件仅 Android 引擎派发，iOS 无需（由 openURL 实时分发）
• uni-app（vue）项目的 .vue / .js 中 #ifdef APP-ANDROID / APP-IOS 不生效（该宏仅 .uts 文件有效，uni-app x 项目例外）。如需区分平台，请用 uni.getSystemInfoSync().platform === "android" 运行时判断
• uni-app 基座需要重新制作自定义基座 / 云打包后原生改动才生效；前端逻辑（如上面示例）改完重新运行即可
• 文件会被复制到插件缓存目录，使用完毕后请调用清理 API

权限

文件读写：本插件仅读写应用自身沙盒缓存/文档目录，不申请存储权限。