288 lines
7.0 KiB
Markdown
288 lines
7.0 KiB
Markdown
# G3File 文件管理组件
|
||
|
||
## 概述
|
||
|
||
G3File 是一个基于 jQuery 的文件管理组件，提供文件上传、预览、下载、删除等功能，支持阿里云 OSS 上传和自定义上传。
|
||
|
||
## 文件结构
|
||
|
||
```
|
||
g3-file/
|
||
├── index.js # 主组件代码
|
||
├── index.css # 样式文件
|
||
├── common.js # 工具函数
|
||
├── icon.js # 图标定义
|
||
├── language.js # 语言配置
|
||
└── libs/ # 第三方依赖
|
||
├── FileSaver.min.js
|
||
└── jszip.min.js
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 引入依赖
|
||
|
||
```html
|
||
<!-- 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" />
|
||
```
|
||
|
||
### 初始化组件
|
||
|
||
```javascript
|
||
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` | 自定义操作菜单，返回菜单项数组 |
|
||
|
||
### 上传配置
|
||
|
||
```javascript
|
||
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 // 自定义上传函数
|
||
}
|
||
```
|
||
|
||
### 权限配置
|
||
|
||
```javascript
|
||
globalPermission: {
|
||
upload: true, // 是否允许上传
|
||
download: true, // 是否允许下载
|
||
delete: true, // 是否允许删除
|
||
view: true // 是否允许查看
|
||
}
|
||
```
|
||
|
||
## 文件数据结构
|
||
|
||
```javascript
|
||
{
|
||
_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)
|
||
|
||
设置文件列表，替换现有文件
|
||
|
||
```javascript
|
||
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获取文件对象
|
||
|
||
```javascript
|
||
var file = file.getFileById('file_123');
|
||
```
|
||
|
||
### getSelectedFiles()
|
||
|
||
获取当前选中的文件列表
|
||
|
||
```javascript
|
||
var selected = file.getSelectedFiles();
|
||
```
|
||
|
||
### updateState(state)
|
||
|
||
更新组件状态
|
||
|
||
```javascript
|
||
// 清空选择
|
||
file.updateState({ selectedFiles: [] });
|
||
```
|
||
|
||
### destroy()
|
||
|
||
销毁组件，清理资源
|
||
|
||
```javascript
|
||
file.destroy();
|
||
```
|
||
|
||
## 使用示例
|
||
|
||
### 示例1：基础用法
|
||
|
||
```javascript
|
||
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：双击事件
|
||
|
||
```javascript
|
||
var file = $('#fileContainer').G3File({
|
||
onDblClick: function(file) {
|
||
// 自定义双击处理，优先于默认预览行为
|
||
alert('双击了文件: ' + file.name);
|
||
}
|
||
});
|
||
```
|
||
|
||
### 示例3：上传前确认
|
||
|
||
```javascript
|
||
var file = $('#fileContainer').G3File({
|
||
onUploadBefore: function(pendingFiles) {
|
||
// 返回 Promise 进行异步确认
|
||
return new Promise((resolve) => {
|
||
if (confirm('确定上传 ' + pendingFiles.length + ' 个文件？')) {
|
||
resolve(true);
|
||
} else {
|
||
resolve(false);
|
||
}
|
||
});
|
||
}
|
||
});
|
||
```
|
||
|
||
### 示例4：自定义操作菜单
|
||
|
||
```javascript
|
||
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：删除前确认
|
||
|
||
```javascript
|
||
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()` 方法，避免内存泄漏 |