workspace/code/file-preview/g3-file.md

G3File 文件管理组件

概述

G3File 是一个基于 jQuery 的文件管理组件，提供文件上传、预览、下载、删除等功能，支持阿里云 OSS 上传和自定义上传。

文件结构

g3-file/
├── index.js          # 主组件代码
├── index.css         # 样式文件
├── common.js         # 工具函数
├── icon.js           # 图标定义
├── language.js       # 语言配置
└── libs/             # 第三方依赖
    ├── FileSaver.min.js
    └── jszip.min.js

快速开始

引入依赖

<!-- jQuery -->
<script src="path/to/jquery.min.js"></script>

<!-- G3File 依赖 -->
<script src="g3-file/language.js"></script>
<script src="g3-file/icon.js"></script>
<script src="g3-file/common.js"></script>
<script src="g3-file/index.js"></script>
<link rel="stylesheet" href="g3-file/index.css" />

初始化组件

var file = $('#fileContainer').G3File({
  data: [
    {
      name: 'example.pdf',
      size: 1024000,
      uploadDate: '2024-01-15T10:30:00',
      url: 'http://example.com/example.pdf'
    }
  ],
  previewUrl: 'https://preview.example.com?url=',
  onUploadSuccess: function(file) {
    console.log('上传成功:', file);
  }
});

配置选项

基础配置

配置项	类型	默认值	说明
data	Array	[]	初始化时的文件数据
mode	String	'aliyun'	上传模式
language	String	'zh-CN'	语言（zh-CN/en/ru）
maxFileSize	Number	10485760	最大文件大小（字节）
previewUrl	String	''	文件预览服务地址

回调函数

配置项	参数	说明
onDeleteBefore	files	删除前回调，返回 false/Promise/Function 可阻止删除
onDelete	files	删除后回调
onDownload	files	下载回调
onSelect	files	文件选中回调
onUpload	pendingFiles	上传开始回调
onUploadBefore	pendingFiles	上传前回调，返回 false/Promise/Function 可阻止上传
onUploadSuccess	file	单个文件上传成功回调
onUploadError	file, error	单个文件上传失败回调
onUploadComplete	successCount, failCount	全部上传完成回调
onDblClick	file	文件双击回调，优先于默认预览行为
customActionMenu	file	自定义操作菜单，返回菜单项数组

上传配置

uploadConfig: {
  aliyun: {
    getAliyunKey: function() {
      // 返回 Promise，包含阿里云 OSS 凭证
      return Promise.resolve({
        accessid: 'your-access-key',
        callback: '',
        dir: 'upload/',
        expire: 1704067200,
        host: 'https://your-bucket.oss-cn-hangzhou.aliyuncs.com',
        policy: 'your-policy',
        signature: 'your-signature'
      });
    }
  },
  customUpload: null // 自定义上传函数
}

权限配置

globalPermission: {
  upload: true,   // 是否允许上传
  download: true, // 是否允许下载
  delete: true,   // 是否允许删除
  view: true      // 是否允许查看
}

文件数据结构

{
  _id: 'unique-id',           // 文件唯一标识符（自动生成）
  name: 'example.pdf',        // 文件名
  size: 1024000,              // 文件大小（字节）
  uploadDate: '2024-01-15T10:30:00', // 上传日期（ISO格式）
  url: 'http://example.com/example.pdf', // 文件访问URL
  file: null,                 // 本地File对象（仅待上传文件有）
  status: 'uploaded'          // 文件状态：pending/uploading/uploaded/failed
}

API 方法

setFiles(files)

设置文件列表，替换现有文件

file.setFiles([
  { name: 'file1.pdf', size: 1024, uploadDate: '2024-01-01', url: '' },
  { name: 'file2.jpg', size: 2048, uploadDate: '2024-01-02', url: 'http://example.com/file2.jpg' }
]);

getFileById(fileId)

根据文件ID获取文件对象

var file = file.getFileById('file_123');

getSelectedFiles()

获取当前选中的文件列表

var selected = file.getSelectedFiles();

updateState(state)

更新组件状态

// 清空选择
file.updateState({ selectedFiles: [] });

destroy()

销毁组件，清理资源

file.destroy();

使用示例

示例1：基础用法

var file = $('#fileContainer').G3File({
  data: [],
  previewUrl: 'https://preview.example.com?url=',
  onUploadSuccess: function(file) {
    console.log('上传成功:', file.name);
  },
  onDelete: function(files) {
    console.log('删除文件:', files.length);
  }
});

示例2：双击事件

var file = $('#fileContainer').G3File({
  onDblClick: function(file) {
    // 自定义双击处理，优先于默认预览行为
    alert('双击了文件: ' + file.name);
  }
});

示例3：上传前确认

var file = $('#fileContainer').G3File({
  onUploadBefore: function(pendingFiles) {
    // 返回 Promise 进行异步确认
    return new Promise((resolve) => {
      if (confirm('确定上传 ' + pendingFiles.length + ' 个文件？')) {
        resolve(true);
      } else {
        resolve(false);
      }
    });
  }
});

示例4：自定义操作菜单

var file = $('#fileContainer').G3File({
  customActionMenu: function(file) {
    return [
      {
        title: '审核',
        onClick: function(file) {
          alert('审核文件: ' + file.name);
        }
      },
      {
        title: '编辑',
        onClick: function(file) {
          alert('编辑文件: ' + file.name);
        },
        disabled: false // 可选，是否禁用
      }
    ];
  }
});

示例5：删除前确认

var file = $('#fileContainer').G3File({
  onDeleteBefore: function(files) {
    // 返回 Promise 进行异步确认（与 onUploadBefore 用法一致）
    return new Promise((resolve) => {
      if (confirm('确定删除 ' + files.length + ' 个文件？')) {
        resolve(true);
      } else {
        resolve(false);
      }
    });
  }
});

事件处理

双击行为优先级

1. 如果配置了 onDblClick 回调，优先执行回调
2. 如果未配置且文件已上传、可预览、有URL，则在新窗口打开预览

支持的预览文件类型

组件会排除以下不可预览的文件类型：

• 压缩包：.rar, .zip, .7z, .tar, .gz, .bz2
• 可执行文件：.exe, .dll, .bin, .msi, .cab, .rpm, .deb, .apk, .ipa
• 数据库文件：.dat, .db, .sqlite
• 临时文件：.bak, .tmp, .log, .cache
• 光盘镜像：.iso

浏览器兼容性

支持 IE11+ 和现代浏览器（Chrome、Firefox、Safari、Edge）

注意事项

1. 使用阿里云 OSS 上传时，必须配置 uploadConfig.aliyun.getAliyunKey 函数
2. 文件大小限制通过 maxFileSize 配置，默认 10MB
3. 预览功能依赖 previewUrl 配置的外部预览服务
4. 销毁组件时请调用 destroy() 方法，避免内存泄漏