更新记录

1.0.0（2026-08-10）

首发

平台兼容性

uni-app(3.1.0)

uni-app x(3.1.0)

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. 异步操作

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

版本信息