SepUpload 上传 v1.0

点击上传 · 拖拽上传 · 粘贴上传 · 三种列表模式（text / picture / picture-card）· beforeUpload 钩子 · customRequest 自定义上传

0. HTML 声明式标签 — SepBase.autoInit() 自动驱动

HTML 声明式标签

1. 基本点击上传 — text 列表模式

HTML 声明式标签
JS API 初始化 — 单文件上传
JS API 初始化 — 多文件上传

2. 拖拽上传 — drag 模式

HTML 声明式标签
JS API 初始化 — 拖拽上传区

3. 图片列表模式 — picture 缩略图

HTML 声明式标签
JS API 初始化 — picture 模式

4. 图片卡片模式 — picture-card 网格

HTML 声明式标签
JS API 初始化 — picture-card 模式

5. 文件类型与大小限制

HTML 声明式标签 — 仅图片 (image/*)
HTML 声明式标签 — 仅 PDF (.pdf)
HTML 声明式标签 — 最多 3 个文件
JS API 初始化 — 仅图片 (image/*)
JS API 初始化 — 仅 PDF (.pdf)
JS API 初始化 — 最多 3 个文件

6. beforeUpload 钩子 & 生命周期回调

HTML 声明式标签 — beforeUpload 拦截大文件
JS API 初始化 — beforeUpload 拦截大文件
JS API 初始化 — onChange / onSuccess / onError 回调

7. 实例方法 & 状态控制

JS API 初始化 — 方法 & 状态控制

8. 拖拽排序 — sortable

HTML 声明式标签 — 拖拽排序
JS API 初始化 — 拖拽排序 + onSort

9. 自定义上传 — customRequest

JS API 初始化 — 模拟异步上传（1.5s 延迟）

10. 文件转换 / 下载 / 预览

HTML 声明式标签 — 显示下载按钮
JS API 初始化 — transformFile + onDownload + onPreview

11. 分片上传 — chunk

HTML 声明式标签 — 1MB 分片
JS API 初始化 — 分片上传 + 进度控制

12. 文件夹 / 拍照 / 禁用 / Headers

HTML 声明式标签 — 文件夹上传
JS API 初始化 — 拍照模式 (mobile)
JS API 初始化 — 禁用状态 + Headers

13. 增强功能：函数 action / 并发控制 / 进度条颜色 / LIST_IGNORE

JS API 初始化 — 动态 action + 并发限制 + 进度条颜色
JS API 初始化 — LIST_IGNORE 跳过 .gitkeep 文件（添加其他文件正常）
JS API 初始化 — isImageUrl 自定义缩略图 + className / style
JS API 初始化 — beforeRemove 确认删除 + showInfo/strokeWidth 定制

14. i18n 多语言：text / hint 支持 i18n key，语言切换自动刷新

点击切换全局语言，下方两个实例文案会自动更新
JS API 初始化 — 显式 i18n key（text: 'upload.text'）
JS API 初始化 — 不设 text/hint，自动取 i18n 默认值（拖拽区）

15. 内置图片灯箱：点击图片预览，支持缩放 / 旋转 / 键盘导航

JS API 初始化 — picture-card 模式（点击图片打开灯箱）
JS API 初始化 — picture 模式（点击预览按钮打开灯箱）

16. 图片裁剪：上传后弹出裁剪框，确认后上传

JS API 初始化 — 自由裁剪
JS API 初始化 — 1:1 头像裁剪
JS API 初始化 — 16:9 封面裁剪

17. 图片自动压缩：上传前按最大边/质量压缩

JS API 初始化 — 最大边 1280，质量 0.8
JS API 初始化 — 最大边 800，质量 0.6（更激进）

18. EXIF 方向修正 + 文件类型图标

JS API 初始化 — 自动修正手机照片 EXIF 方向
picture 模式上传非图片文件 — 自动显示对应类型图标（pdf/doc/excel/zip...）
灯箱已内置下载按钮：打开图片灯箱后点击 ⬇ 图标即可下载当前图片（支持旋转后导出）

19. 增强功能 — 尺寸校验 / 严格类型 / 去重 / 裁剪平移缩放

图片尺寸校验：宽高限制 + 严格 MIME 类型校验（防改后缀绕过）
文件去重：相同文件名 + 大小自动拒绝
裁剪器增强：滚轮缩放 / 拖拽平移 / 左右旋转 / 任意角度

20. 断点续传 — 分片上传 + 暂停/继续 + 已上传分片自动跳过

启用 resumable 后，文件分片上传，支持暂停/继续，刷新页面后重新选择同一文件可自动跳过已上传分片

21. 高级特性 — 超时 · 自动重试 · 自定义拖拽提示

timeout 超时中断、retry 失败自动重试、dragHintText 拖拽自定义提示文案、persist 刷新后恢复已上传文件

详细说明

组件定位

SepUpload 提供企业级文件上传能力，支持点击 / 拖拽 / 粘贴三种交互，三种列表展示模式（text / picture / picture-card），内置图片压缩裁剪、MIME 严格校验、断点续传、状态持久化等完整能力链。

核心用法

  • action — 上传接口地址，必填
  • listType — 列表模式：text / picture / picture-card
  • drag — 启用拖拽上传区
  • accept — 文件类型限制，如 image/*,.pdf
  • strictAccept — 启用文件头魔数严格校验
  • dedupe — 启用文件去重（name+size）
  • maxCount — 最大文件数量
  • maxSize — 单个文件最大字节数
  • beforeUpload — 上传前钩子，支持 Promise
  • customRequest — 自定义上传实现

图片处理

  • compress — 图片压缩，支持 maxWidth/maxHeight/quality
  • compress.toWebp — 压缩时输出 WebP 格式
  • fixOrientation — 修正 JPEG EXIF 方向
  • imageMin/MaxWidth/Height — 图片尺寸校验
  • SepCropper — 内置图片裁剪器，支持缩放/平移/旋转

断点续传

  • chunk — 启用分片上传
  • chunkSize — 分片大小，默认 2MB
  • chunkConcurrent — 分片并发数
  • chunkRetry — 单片失败重试次数
  • resumable — 启用断点续传
  • checkChunk — 服务端分片查询回调
  • mergeChunk — 分片合并回调
  • getChunkParams — 自定义分片参数
  • onBeforeResume — 续传前拦截钩子

传输控制

  • retry — 上传失败自动重试次数
  • timeout — 上传超时毫秒数
  • showSpeed — 显示上传速度与剩余时间
  • maxConcurrent — 多文件并发上传数
  • headers / data — 自定义请求头/附加数据
  • onChunkProgress — 单片上传进度回调

状态持久化

  • persist — 启用 localStorage 持久化
  • persistKey — 自定义存储键名
  • 仅持久化已上传完成的文件元数据
  • 刷新页面后自动恢复已上传文件列表
  • clearFiles() 同步清除持久化记录

注意事项

  • drag 模式下全局监听 dragenter/dragleave
  • dragHintText 拖拽时临时替换提示文案
  • picture / picture-card 模式自动生成图片缩略图
  • 粘贴上传仅支持图片类型文件
  • maxCount 达到上限后自动隐藏上传按钮
  • strictAccept 通过文件头魔数检测，防止改后缀绕过

API 速查

getFileList()setFileList(list) clearFiles()upload() abort(file)retry(file) pause(file)resume(file) pauseAll()resumeAll() openFileDialog()clearPersist() setDisabled(v)setMaxCount(v) setMaxSize(v)getState() setState({})subscribe(fn) destroy()

14. 自动化断言