u
This commit is contained in:
oneao committed
1 parent
3620369d47
commit
217838c615
11 files changed
+1268
-1022
No files matched your search
@@ -0,0 +1,288 @@
|
||||
# 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()` 方法，避免内存泄漏
|
||||
Reference in new issue
Block a user