# 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()` 方法，避免内存泄漏