更新记录

2.0.0（2025-06-20） 下载此版本

第一个版本

1.0.0（2024-12-20） 下载此版本

第一次提交

平台兼容性

uni-app

PiaoFileList 文件列表插件

概述

PiaoFileList 是一个专业的文件列表展示插件，专为 uni-app 项目设计。插件采用低耦合设计，完全由父组件提供数据，支持云端与本地文件状态对比显示。

核心特性

1. 🎯 插件定位

• 纯展示组件，不主动获取本地数据
• 完全由父组件提供云端数据和本地数据
• 对比显示文件的云端/本地状态
• 低耦合，易于集成和维护

2. 📁 文件管理功能

• 支持文件夹层级结构显示
• 面包屑导航
• 全文件搜索（支持跨文件夹搜索）
• 文件状态显示（已同步/仅云端/仅本地/同步中/错误）

3. 📱 交互功能

• 文件点击触发下载和打开
• 文件夹点击进入下级目录
• 多选模式支持
• 长按进入选择模式

4. 🔄 下载与打开

• 点击文件自动下载
• 下载完成后使用系统默认应用打开
• 支持各种文件格式的图标显示

数据结构

FileData 接口

interface FileData {
  id: string; // 唯一标识
  name: string; // 文件名（不含扩展名）
  ext?: string; // 文件扩展名（不含点号），如: "pdf", "docx"
  size?: number; // 文件大小（字节）
  modifiedTime?: string; // 修改时间（ISO格式）
  isFolder: boolean; // 是否为文件夹
  cloudPath: string; // 云端路径，格式：前缀 + 面包屑路径
  isLocal?: boolean; // 是否本地存在
  isSynced?: boolean; // 是否已同步
  fileURL?: string; // 文件下载链接
}

重要说明

1. 文件名分离：name 字段不包含扩展名，扩展名存储在 ext 字段中
2. 路径结构：使用 cloudPath 表示文件层级关系，格式为 前缀\案件名\文件夹1\文件夹2
3. 下载链接：使用 fileURL 字段提供文件下载地址

基本使用

1. 引入组件

<template>
  <piao-file-list
    :files="currentFiles"
    :all-files="allFiles"
    :cloud-path-prefix="CLOUD_PATH_PREFIX"
    :searchable="true"
    @file-click="handleFileClick"
    @navigation-change="handleNavigationChange"
  />
</template>

<script setup>
import PiaoFileList from '@/uni_modules/piao-file-list/components/piao-file-list/piao-file-list.vue'
import type { FileData } from '@/uni_modules/piao-file-list/components/piao-file-list/utils'

const CLOUD_PATH_PREFIX = '大成律师团队\\'
const currentFiles = ref<FileData[]>([])
const allFiles = ref<FileData[]>([])
</script>

2. 数据示例

const fileData = [
  // 文档文件
  {
    id: "doc-1",
    name: "合同纠纷起诉书",
    ext: "pdf",
    isFolder: false,
    cloudPath: "大成律师团队\\王某诉李某合同纠纷案",
    size: 2048576,
    modifiedTime: "2024-01-15T10:30:00Z",
    isLocal: true,
    isSynced: true,
    fileURL: "https://example.com/files/起诉书.pdf",
  },
  // 文件夹
  {
    id: "folder-1",
    name: "证据材料",
    isFolder: true,
    cloudPath: "大成律师团队\\王某诉李某合同纠纷案",
    modifiedTime: "2024-01-14T15:20:00Z",
    isLocal: true,
    isSynced: true,
  },
];

组件属性

事件

事件处理示例

// 文件点击处理
const handleFileClick = (file) => {
  if (file.isFolder) {
    // 进入文件夹
    enterFolder(file.name);
  } else {
    // 文件会自动触发下载和打开
    console.log("文件被点击:", file.name);
  }
};

// 搜索导航处理
const handleNavigationChange = (cloudPath) => {
  // 根据搜索结果导航到对应文件夹
  updateCurrentPath(cloudPath);
  updateFileList();
};

高级功能

1. 全文搜索

插件支持在所有文件中进行搜索：

// 提供完整的文件数据用于搜索
const allFiles = ref([...所有案件的所有文件]);

// 搜索时会在 allFiles 中查找，点击结果会导航到对应位置

2. 状态管理

插件通过对比云端和本地数据显示文件状态：

• 已同步：isLocal: true, isSynced: true
• 仅云端：isLocal: false, fileURL: "..."
• 仅本地：isLocal: true, isSynced: false
• 同步中：由父组件控制状态
• 错误：异常状态

3. 层级导航

使用 cloudPath 实现文件夹层级：

// 根目录
cloudPath: "大成律师团队\\王某诉李某合同纠纷案";

// 子文件夹
cloudPath: "大成律师团队\\王某诉李某合同纠纷案\\证据材料";

// 深层文件夹
cloudPath: "大成律师团队\\王某诉李某合同纠纷案\\证据材料\\通话录音";

最佳实践

1. 数据提供

• 父组件负责提供所有数据，包括云端文件列表和本地文件状态
• 定期更新文件状态，确保显示准确
• 合理设置 cloudPath 以支持正确的层级导航

2. 性能优化

• 大量文件时，考虑分页加载
• 合理使用 allFiles 属性，避免传递过多数据
• 及时清理不需要的文件引用

3. 用户体验

• 提供明确的加载状态反馈
• 处理网络异常情况
• 为不同文件类型提供合适的图标

文件类型支持

插件内置支持以下文件类型图标：

• 文档：pdf, doc, docx, txt, rtf, odt, md
• 表格：xlsx, xls, csv
• 图片：jpg, jpeg, png, gif, bmp, webp, svg
• 视频：mp4, avi, mov, wmv, flv, mkv, webm
• 音频：mp3, wav, aac, flac, ogg
• 压缩：zip, rar, 7z, tar, gz, bz2
• 其他：默认文件图标

注意事项

1. 插件定位：这是一个纯展示组件，不会主动获取本地文件信息
2. 数据格式：确保传入的 FileData 格式正确，特别是 cloudPath 字段
3. 下载功能：需要确保 fileURL 可访问，下载失败会有相应提示
4. 权限处理：文件打开可能需要相应的系统权限
5. 平台兼容：某些功能可能在不同平台表现不同，请做好兼容性测试

版本：v1.0.0
作者：Piao Team
更新时间：2024-01-15