更新记录

1.0.2（2025-06-06） 下载此版本

修复不能正确获取PDF路径的问题。 不知道什么原因，获取分享的音频文件（通话录音）时，部分文件不能获取正确的路径，以后再测试

1.0.1（2025-06-06） 下载此版本

更新了文档说明

1.0.0（2025-06-06） 下载此版本

第一个版本

平台兼容性

uni-app

piao-file-manager

一个功能强大的 uni-app 文件管理模块，支持文件选择、分享文件处理、进度回调和自动临时文件清理。

🌟 功能特性

• ✅ 文件选择 - 支持选择单个或多个文件
• ✅ 分享文件处理 - 处理其他应用分享到当前应用的单个或多个文件
• ✅ 进度回调 - 实时显示文件复制进度
• ✅ 自动路径解析 - 智能处理各种 URI 格式
• ✅ 临时文件管理 - 自动清理过期的临时文件
• ✅ 完整文件信息 - 获取文件大小、名称、路径等详细信息
• ✅ 错误处理 - 完善的异常处理和用户提示
• ✅ Android 平台支持 - 专为 Android 平台优化

📦 安装

方式一：HBuilderX 插件市场

1. 在 HBuilderX 中打开插件市场
2. 搜索 "piao-file-manager"
3. 点击安装

方式二：手动安装

1. 将整个 piao-file-manager 文件夹复制到项目的 uni_modules 目录下
2. 重新编译项目

🚀 快速开始

1. 配置 AndroidManifest.xml（接收分享文件必需）

在项目根目录下创建 AndroidManifest.xml 文件：

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="__UNIAPPID__">
  <application>
    <activity android:name="io.dcloud.PandoraEntry">
      <!-- 添加文件分享的Intent过滤器 -->
      <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <action android:name="android.intent.action.SEND_MULTIPLE" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="*/*" />
      </intent-filter>
    </activity>
  </application>
  <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
  <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
</manifest>

2. 应用初始化

在 App.vue 中初始化文件管理器：

import { startTempFileCleanup } from "@/uni_modules/piao-file-manager/js_sdk/FileManager.js";

export default {
  onLaunch() {
    // 启动定期清理任务
    startTempFileCleanup();
  },
};

💡 使用示例

1. 选择单个文件

import { selectFile } from "@/uni_modules/piao-file-manager/js_sdk/FileManager.js";

async function chooseFile() {
  try {
    const fileInfo = await selectFile({
      : (current, total) => {
        if (total > 0) {
          // 显示百分比进度
          const percentage = Math.round((current / total) * 100);
          uni.showLoading({
            title: `复制中 ${percentage}%`,
            mask: true,
          });
        } else {
          // 无法确定总大小时，显示已传输字节数
          const sizeInMB = (current / (1024 * 1024)).toFixed(2);
          uni.showLoading({
            title: `已复制 ${sizeInMB}MB`,
            mask: true,
          });
        }
      },
    });

    if (fileInfo) {
      console.log("选择的文件:", {
        name: fileInfo.name,
        size: fileInfo.sizeString,
        path: fileInfo.path,
      });

      // 这里可以处理文件，例如上传到服务器
      await uploadFile(fileInfo.path);

      uni.showToast({
        title: "文件处理成功",
        icon: "success",
      });
    } else {
      uni.showToast({
        title: "已取消选择",
        icon: "none",
      });
    }
  } catch (error) {
    console.error("选择文件失败:", error);
    uni.showToast({
      title: "选择文件失败",
      icon: "error",
    });
  }
}

2. 选择多个文件

import { selectMultipleFiles } from "@/uni_modules/piao-file-manager/js_sdk/FileManager.js";

async function chooseMultipleFiles() {
  try {
    const files = await selectMultipleFiles({
      maxCount: 10, // 最多选择10个文件

      // 整体进度回调
      : (current, total) => {
        uni.showLoading({
          title: `处理文件 ${current}/${total}`,
          mask: true,
        });
      },

      // 单个文件进度回调
      onFileProgress: (fileIndex, fileName, progress) => {
        console.log(`${fileName} 进度: ${progress}%`);
      },
    });

    if (files && files.length > 0) {
      console.log(`选择了 ${files.length} 个文件:`);
      files.forEach((file, index) => {
        console.log(`文件${index + 1}:`, {
          name: file.name,
          size: file.sizeString,
          path: file.path,
        });
      });

      // 批量处理文件
      for (let i = 0; i < files.length; i++) {
        const file = files[i];
        uni.showLoading({
          title: `处理文件 ${i + 1}/${files.length}`,
          mask: true,
        });

        // 这里可以处理每个文件，例如上传到服务器
        await uploadFile(file.path);
      }

      uni.showToast({
        title: `成功处理 ${files.length} 个文件`,
        icon: "success",
      });
    } else {
      uni.showToast({
        title: "未选择文件",
        icon: "none",
      });
    }
  } catch (error) {
    console.error("选择多文件失败:", error);
    uni.showToast({
      title: "选择失败",
      icon: "error",
    });
  }
}

3. 处理分享文件

import { getSharePath } from "@/uni_modules/piao-file-manager/js_sdk/FileManager.js";

// 在App.vue的onShow中调用
async function handleSharedFiles() {
  try {
    const sharedFiles = await getSharePath({
      // 整体进度回调
      : (current, total) => {
        uni.showLoading({
          title: `处理分享文件 ${current}/${total}`,
        });
      },

      // 单个文件进度回调
      onFileProgress: (fileIndex, fileName, progress) => {
        console.log(`处理 ${fileName}: ${progress}%`);
      },
    });

    uni.hideLoading();

    if (sharedFiles) {
      if (Array.isArray(sharedFiles)) {
        // 多个分享文件
        console.log(`收到 ${sharedFiles.length} 个分享文件:`);
        sharedFiles.forEach((file, index) => {
          console.log(`分享文件${index + 1}:`, {
            name: file.name,
            size: file.sizeString,
            path: file.path,
          });
        });

        // 处理多个分享文件
        for (const file of sharedFiles) {
          await processSharedFile(file);
        }
      } else {
        // 单个分享文件
        console.log("收到分享文件:", {
          name: sharedFiles.name,
          size: sharedFiles.sizeString,
          path: sharedFiles.path,
        });

        // 处理单个分享文件
        await processSharedFile(sharedFiles);
      }
    }
  } catch (error) {
    console.error("处理分享文件失败:", error);
    uni.showToast({
      title: "处理分享文件失败",
      icon: "error",
    });
  }
}

// 处理分享文件的函数
async function processSharedFile(fileInfo) {
  try {
    // 这里可以根据文件类型进行不同处理
    const fileExt = fileInfo.name.split(".").pop().toLowerCase();

    switch (fileExt) {
      case "jpg":
      case "jpeg":
      case "png":
        // 处理图片文件
        await processImage(fileInfo);
        break;
      case "pdf":
        // 处理PDF文件
        await processPDF(fileInfo);
        break;
      default:
        // 处理其他类型文件
        await processOtherFile(fileInfo);
    }
  } catch (error) {
    console.error("处理文件失败:", error);
    throw error;
  }
}

4. 临时文件管理

import {
  getTempFilesInfo,
  cleanTempFiles,
} from "@/uni_modules/piao-file-manager/js_sdk/FileManager.js";

// 检查临时文件状态
async function checkTempFiles() {
  try {
    const info = await getTempFilesInfo();
    console.log(`临时文件: ${info.count}个`);
    console.log(`占用空间: ${(info.totalSize / 1024 / 1024).toFixed(2)}MB`);

    // 如果临时文件过多，进行清理
    if (info.count > 10 || info.totalSize > 100 * 1024 * 1024) {
      // 超过100MB
      const cleanedCount = await cleanTempFiles();
      uni.showToast({
        title: `清理了 ${cleanedCount} 个文件`,
        icon: "success",
      });
    }
  } catch (error) {
    console.error("检查临时文件失败:", error);
  }
}

📖 API 文档

文件选择

selectFile(options?)

选择单个文件。

参数：

• options (Object, 可选) - 配置选项
  • onProgress (Function, 可选) - 进度回调函数
  • 参数：
    • current (Number) - 当前已处理的字节数
    • total (Number) - 总字节数，如果无法获取则为 -1

返回值：

• Promise<Object|null> - 文件信息对象或 null
  • 文件信息对象结构：

    {
    path: string,          // 文件路径
    name: string,          // 文件名
    size: number,          // 文件大小(字节)
    sizeString: string,    // 格式化的文件大小
    exists: boolean,       // 文件是否存在
    canRead: boolean,      // 是否可读
    isTemp: boolean,       // 是否为临时文件
    originalUri?: string,  // 原始URI字符串
    }

selectMultipleFiles(options?)

选择多个文件。

参数：

• options (Object, 可选) - 配置选项
  • maxCount (Number, 可选) - 最大文件数量，默认不限制
  • onProgress (Function, 可选) - 整体进度回调函数
  • 参数：
    • current (Number) - 当前处理的文件索引
    • total (Number) - 总文件数
    • fileIndex (Number) - 当前文件索引
    • fileCount (Number) - 总文件数
  • onFileProgress (Function, 可选) - 单个文件进度回调
  • 参数：
    • fileIndex (Number) - 文件索引
    • fileName (String) - 文件名
    • progress (Number) - 进度百分比(0-100)
  • fallbackToSingle (Boolean, 可选) - 是否在不支持多选时降级到单文件选择，默认 true

返回值：

• Promise<Array|null> - 文件信息数组或 null
  • 数组中的每个元素都是文件信息对象，结构同 selectFile 的返回值

文件分享

getSharePath(options?)

获取分享文件。

参数：

• options (Object, 可选) - 配置选项
  • onProgress (Function, 可选) - 整体进度回调函数
  • 参数：
    • current (Number) - 当前处理的文件索引
    • total (Number) - 总文件数
    • fileIndex (Number) - 当前文件索引
    • fileCount (Number) - 总文件数
  • onFileProgress (Function, 可选) - 单个文件进度回调
  • 参数：
    • fileIndex (Number) - 文件索引
    • fileName (String) - 文件名
    • progress (Number) - 进度百分比(0-100)

返回值：

• Promise<Object|Array|null> - 单个文件信息对象、文件信息数组或 null
  • 单个文件时返回文件信息对象，结构同 selectFile 的返回值
  • 多个文件时返回文件信息数组，结构同 selectMultipleFiles 的返回值

临时文件管理

startTempFileCleanup(interval?, maxAge?)

启动定期清理任务。

参数：

• interval (Number, 可选) - 清理间隔毫秒数，默认 1 小时
• maxAge (Number, 可选) - 文件最大保留时间毫秒数，默认 24 小时

cleanTempFiles(maxAge?)

手动清理临时文件。

参数：

• maxAge (Number, 可选) - 文件最大保留时间毫秒数，默认 0(清理所有)

返回值：

• Promise<Number> - 清理的文件数量

getTempFilesInfo()

获取临时文件统计信息。

返回值：

• Promise<Object> - 统计信息对象

  {
  count: number,     // 临时文件数量
  totalSize: number  // 总大小(字节)
  }

⚠️ 注意事项

1. 仅支持 Android 平台
2. 需要配置相应的权限
3. 分享文件功能需要配置 AndroidManifest.xml
4. 建议定期清理临时文件

📝 更新日志

v1.1.0

• 新增多文件选择功能
• 增强分享文件处理
• 支持批量进度回调
• 新增文件数量限制
• 优化临时文件管理

v1.0.0

• 基础文件选择功能
• 分享文件处理
• 进度回调支持
• 自动临时文件清理

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request 来帮助改进这个项目！