更新记录

1.0.0（2026-06-29）

首发

平台兼容性

uni-app(3.8.1)

yc-FileSlice 文件切片插件调用文档

功能简介

yc-FileSlice 是一个基于 UTS 开发的跨平台文件切片插件，支持 Android 和 iOS 平台。提供文件分片切片、切片数据读取、切片清理以及 Base64 转换功能。

支持平台

安装方式

将 yc-FileSlice 文件夹放置在项目的 uni_modules 目录下即可。

uni_modules/
└── yc-FileSlice/
    └── utssdk/

API 文档

1. sliceFile - 文件切片

将大文件按照指定大小切分成多个分片文件。

参数说明

回调参数

onProgress(progress)

onComplete(result)

onError(error)

调用示例

import { sliceFile } from '@/utils/file-slicer'

const controller = sliceFile({
  filePath: '/path/to/source.mp4',
  savePath: '_doc/file-slices/',
  sliceSize: 5 * 1024 * 1024, // 5MB
  sliceSuffixName: 'tmp',
  : (progress) => {
    console.log('进度:', progress.index, '/', progress.total)
  },
  onComplete: (result) => {
    console.log('切片完成，共', result.totalChunks, '个分片')
    console.log('分片路径:', result.chunkPaths)
  },
  onError: (error) => {
    console.error('切片失败:', error)
  }
})

// 取消切片
controller.cancel()

2. getSliceData - 获取切片数据

读取所有切片文件并合并为一个 ByteArray 对象。

参数说明

回调参数

onComplete(result)

onError(error)

调用示例

import { getSliceData } from '@/utils/file-slicer'

getSliceData({
  chunkPaths: result.chunkPaths, // sliceFile 返回的 chunkPaths
  onComplete: (result) => {
    console.log('获取成功，数据大小:', result.data.length)
    // 可以使用 result.data 进行后续操作，如上传等
  },
  onError: (error) => {
    console.error('获取失败:', error)
  }
})

3. cleanSliceData - 清理切片数据

删除指定的切片文件。

参数说明

回调参数

onComplete(result)

onError(error)

调用示例

import { cleanSliceData } from '@/utils/file-slicer'

cleanSliceData({
  chunkPaths: result.chunkPaths, // sliceFile 返回的 chunkPaths
  onComplete: (result) => {
    console.log('清理成功，删除', result.deletedCount, '个文件')
  },
  onError: (error) => {
    console.error('清理失败:', error)
  }
})

4. convertToBase64 - Base64 转换

将文件内容转换为 Base64 编码字符串。

参数说明

回调参数

onProgress(progress)

onComplete(result)

onError(error)

调用示例

import { convertToBase64 } from '@/utils/file-slicer'

const controller = convertToBase64({
  filePath: '/path/to/file.jpg',
  chunkSize: 2 * 1024 * 1024, // 2MB
  : (progress) => {
    console.log('转换进度:', progress.index, '/', progress.total)
  },
  onComplete: (result) => {
    console.log('转换完成')
    console.log('Base64 长度:', result.base64.length)
  },
  onError: (error) => {
    console.error('转换失败:', error)
  }
})

// 取消转换
controller.cancel()

平台检测辅助函数

import { isAndroid, isIOS, isWechatMiniProgram, isH5 } from '@/utils/file-slicer'

if (isAndroid()) {
  console.log('当前平台: Android')
}

if (isIOS()) {
  console.log('当前平台: iOS')
}

if (isWechatMiniProgram()) {
  console.log('当前平台: 微信小程序')
}

if (isH5()) {
  console.log('当前平台: H5')
}

完整使用流程示例

import { sliceFile, getSliceData, cleanSliceData } from '@/utils/file-slicer'

// 1. 选择文件后开始切片
function onFileSelected(filePath) {
  sliceFile({
    filePath: filePath,
    savePath: '_doc/file-slices/',
    sliceSize: 5 * 1024 * 1024, // 5MB 每片
    sliceSuffixName: 'chunk',
    : (progress) => {
      console.log(`切片进度: ${progress.index + 1}/${progress.total}`)
    },
    onComplete: (result) => {
      console.log('切片完成，共', result.totalChunks, '个分片')
      // 保存 result 供后续使用
      window.sliceResult = result
    },
    onError: (error) => {
      console.error('切片失败:', error)
    }
  })
}

// 2. 获取切片数据（合并所有分片）
function onGetSliceData() {
  const result = window.sliceResult
  if (!result || !result.chunkPaths) {
    console.error('请先进行切片')
    return
  }

  getSliceData({
    chunkPaths: result.chunkPaths,
    onComplete: (dataResult) => {
      console.log('获取成功，数据大小:', dataResult.data.length)
      // 使用 dataResult.data 进行后续操作
    },
    onError: (error) => {
      console.error('获取失败:', error)
    }
  })
}

// 3. 清理切片文件
function onCleanSliceData() {
  const result = window.sliceResult
  if (!result || !result.chunkPaths) {
    console.error('请先进行切片')
    return
  }

  cleanSliceData({
    chunkPaths: result.chunkPaths,
    onComplete: (cleanResult) => {
      console.log('清理成功，删除', cleanResult.deletedCount, '个文件')
      window.sliceResult = null
    },
    onError: (error) => {
      console.error('清理失败:', error)
    }
  })
}

注意事项

1. 文件路径格式

   • App 端推荐使用绝对路径
   • 相对路径如 _doc/file-slices/ 会被自动转换为绝对路径

2. 切片大小建议

   • 小文件（< 100MB）：建议使用 1-5MB
   • 大文件（> 100MB）：建议使用 5-20MB
   • 过小的切片会影响性能，过大会占用过多内存

3. 内存管理

   • getSliceData 会将所有切片加载到内存，大文件请注意内存使用
   • 使用完毕后建议调用 cleanSliceData 清理临时文件

4. 异步操作

   • 所有操作均为异步执行，不会阻塞主线程
   • 通过回调函数获取执行结果

5. MD5 校验

   • 设置 computeMD5: true 可计算每个分片和整个文件的 MD5
   • MD5 值可用于服务端校验数据完整性

6. 断点续传

   • 使用 sliceFileWithResume 方法支持断点续传
   • 提供 taskId 参数，插件会自动保存和恢复切片进度
   • 如果文件未变化，已切片的分片会被跳过

Promise 版本 API

import { sliceFileAsync, convertToBase64Async, getSliceDataAsync, cleanSliceDataAsync } from '@/utils/file-slicer'

// 使用 async/await
async function handleFile() {
  try {
    const result = await sliceFileAsync({
      filePath: '/path/to/file.mp4',
      savePath: '_doc/slices/',
      sliceSize: 5 * 1024 * 1024
    })
    console.log('切片完成:', result.totalChunks)
  } catch (error) {
    console.error('切片失败:', error)
  }
}

MD5 校验功能

import { sliceFile } from '@/utils/file-slicer'

sliceFile({
  filePath: '/path/to/file.mp4',
  savePath: '_doc/slices/',
  sliceSize: 5 * 1024 * 1024,
  computeMD5: true, // 开启 MD5 计算
  : (progress) => {
    console.log('分片 MD5:', progress.chunkMD5)
  },
  onComplete: (result) => {
    console.log('文件 MD5:', result.fileMD5)
    console.log('分片 MD5 列表:', result.chunkMD5s)
  }
})

断点续传功能

import { sliceFileWithResume, getSliceState, cleanSliceState } from '@/utils/file-slicer'

// 使用断点续传
sliceFileWithResume({
  filePath: '/path/to/file.mp4',
  savePath: '_doc/slices/',
  sliceSize: 5 * 1024 * 1024,
  taskId: 'my-upload-task-001', // 唯一任务 ID
  : (progress) => {
    console.log('进度:', progress.index, progress.total)
  },
  onComplete: (result) => {
    console.log('切片完成')
  },
  onError: (error) => {
    console.error('切片失败:', error)
  }
})

// 查询任务状态
getSliceState({
  taskId: 'my-upload-task-001',
  onComplete: (state) => {
    if (state.exists) {
      console.log('已完成分片:', state.completedChunks)
    }
  }
})

// 清理任务状态
cleanSliceState({
  taskId: 'my-upload-task-001'
})

常见问题

Q: 切片时提示"文件不存在"

A: 请检查以下几点：

1. Android 权限：确认已授予 READ_EXTERNAL_STORAGE / WRITE_EXTERNAL_STORAGE 权限
2. 文件路径：确认传入的是有效的绝对路径，可通过 plus.io API 转换相对路径
3. 文件来源：通过 plus.gallery.pick 获取的路径通常可直接使用；若通过其他方式获取，请确认路径格式

Q: Base64 转换结果很长导致内存溢出

A: Base64 编码会使数据膨胀约 33%。对于大文件，建议改用分片上传而非 Base64 转换。如确需 Base64，建议仅用于小文件（< 10MB）。

Q: 回调函数报"已释放"错误

A: 本插件已内置 @UTSJS.keepAlive 和全局引用保持机制，正常情况下不会出现此问题。如仍遇到：

1. 确保使用最新版 HBuilderX（≥ 4.27）
2. 清理编译缓存后重新运行

Q: iOS 端切片后的文件在哪里？

A: iOS 沙盒机制下，切片文件保存在 savePath 指定的 App 沙盒目录内。使用 _doc/ 等相对路径时，框架会自动转换为沙盒绝对路径。

版本信息