更新记录

1.0.1（2026-06-17） 下载此版本

增加内置demo

1.0.0（2026-06-17） 下载此版本

• 初始版本发布
• 支持文件分片上传
• 支持断点续传（需配置 checkApi）
• 支持秒传（服务端返回 uploaded: true）
• 支持并发控制（concurrency 参数）
• 支持失败自动重试（retryCount + retryDelay 参数）
• 支持暂停/继续/取消
• 支持实时进度展示
• 支持图片缩略图预览
• 支持自定义触发器插槽（trigger slot）
• 支持外部文件列表回显（value prop）
• 提供 JS 工具类 SliceUploader，可脱离 UI 组件独立使用
• 所有接口字段名均可配置，适配不同后端规范

平台兼容性

uni-app(5.0)

snail-upload-slice

UniApp 文件分片上传组件，支持分片上传、断点续传、进度展示、秒传、并发控制、失败重试，参数高度可配置。

功能特性

• 分片上传：将大文件切割为多个分片依次或并发上传
• 断点续传：上传前通过 checkApi 检测已上传分片，跳过已完成部分
• 秒传：服务端返回 { uploaded: true } 时直接完成，无需重复上传
• 并发控制：concurrency 控制同时上传分片数，防止占用过多带宽
• 失败重试：分片失败后自动重试，支持自定义重试次数和间隔
• 暂停/继续：随时暂停并从断点恢复
• 进度展示：实时百分比进度条 + 状态文字
• 文件预览：图片显示缩略图，其他类型显示文件图标
• 自定义插槽：通过 trigger 插槽替换默认上传按钮

快速开始

查看示例页面

插件内置了完整的示例页面，帮助你快速上手：

1. 在 HBuilderX 中导入插件后
2. 将 uni_modules/snail-upload-slice/pages/demo 目录复制到你的项目 pages 目录下
3. 在 pages.json 中添加页面配置：

   {
    "path": "pages/demo/index",
    "style": {
      "navigationBarTitleText": "上传组件演示"
    }
   }

4. 运行项目即可查看完整示例

示例页面包含：

• ✅ 基础自动上传示例
• ✅ 手动上传图片示例
• ✅ 自定义触发器示例
• ✅ 实时事件日志展示
• ✅ 服务器地址动态配置

使用说明

组件遵循 easycom 规范，导入插件后无需手动引入，直接使用即可。

<snail-upload-slice
  upload-api="https://your-server.com/api/upload/chunk"
  check-api="https://your-server.com/api/upload/check"
  merge-api="https://your-server.com/api/upload/merge"
  :chunk-size="2 * 1024 * 1024"
  :concurrency="3"
  :retry-count="3"
  accept="all"
  :max-count="9"
  :max-size="100 * 1024 * 1024"
  :auto-upload="true"
  :show-progress="true"
  tip="支持任意格式，单文件不超过100MB"
  @success="onSuccess"
  @error="onError"
  @progress=""
  @change="onChange"
/>

Props 参数

API 配置

上传配置

字段名配置

文件选择配置

UI 配置

Events 事件

Methods 方法

通过 ref 调用组件实例方法：

插槽 Slots

服务端接口规范

checkApi（GET）

请求参数：

fileHash=xxx&fileName=xxx&fileSize=xxx

响应示例（秒传）：

{ "code": 0, "uploaded": true, "url": "https://cdn.example.com/file.zip" }

响应示例（断点续传）：

{ "code": 0, "uploaded": false, "uploadedChunks": [0, 1, 2] }

uploadApi（POST，multipart/form-data）

请求字段：

• chunk：分片文件二进制
• chunkIndex：当前分片索引（从 0 开始）
• chunkTotal：总分片数
• fileHash：文件唯一标识
• fileName：原始文件名
• fileSize：文件总大小

响应示例：

{ "code": 0, "msg": "ok" }

mergeApi（POST，application/json）

请求体：

{ "fileHash": "xxx", "fileName": "xxx.zip", "fileSize": 1024000, "chunkTotal": 5 }

响应示例：

{ "code": 0, "msg": "合并成功", "url": "https://cdn.example.com/xxx.zip" }

直接使用 JS 工具类

import { SliceUploader, UPLOAD_STATUS } from '@/uni_modules/snail-upload-slice/js_sdk/upload-slice.js'

const uploader = new SliceUploader({
  uploadApi: 'https://your-server.com/api/upload/chunk',
  checkApi: 'https://your-server.com/api/upload/check',
  mergeApi: 'https://your-server.com/api/upload/merge',
  chunkSize: 2 * 1024 * 1024,
  concurrency: 3,
  retryCount: 3,
})

uploader
  .on('progress', ({ progress }) => console.log('进度：', progress))
  .on('success', ({ data }) => console.log('成功：', data))
  .on('error', ({ error }) => console.error('失败：', error))

// 开始上传（file 为 uni.chooseFile 返回的 tempFiles[0]）
uploader.start(file)

// 暂停
uploader.pause()

// 继续
uploader.resume()

// 取消
uploader.cancel()