基础属性

defaultFileList

说明默认文件列表
类型 UserFile[]
默认值[]

实时编辑器

function DefaultFileListExample(params) {
  const defaultFileList = [{
    id: 1,
    name: 'default.jpg',
    url: 'https://baidu.com',
  }]

  const options = {
    action: 'https://tiny-uploader-server.vercel.app/file/upload',
  }

  return (
    <Uploader 
      defaultFileList={defaultFileList}
      options={options}
    />
  )
}

结果

tipRender

说明自定义提示内容
类型 null | () => ReactNode
默认值 null

实时编辑器

function TipRenderExample(params) {
  const options = {
    action: 'https://tiny-uploader-server.vercel.app/file/upload',
  }

  return (
    <Uploader 
      options={options} 
      tipRender={() => (
        <div className="tiny-uploader-tip">Click or drag files to this area to upload.</div>
      )}
    />
  )
}

结果

options

说明参数配置
类型 UploaderOptions
默认值

const defaultOptions: UploaderOptions = {
  // input 属性相关
  accept: '*',
  multiple: true,
  // 文件相关
  limit: 10,
  autoUpload: true,
  customGenerateUid: undefined,
  beforeAdd: (_file: FileContext) => true,
  beforeRemove: (_file: FileContext) => true,
  addFailToRemove: true,
  chunkSize: 2 * 1024 * 1024, // 2M
  fakeProgress: true,
  withHash: true,
  useWebWoker: false,
  // 上传逻辑相关
  name: 'file',
  action: '',
  customRequest: null,
  withCredentials: true,
  headers: {},
  data: {},
  requestSucceed: (xhr) => [200, 201, 202, 206].includes(xhr.status),
  maxConcurrency: 6,
  maxRetries: 3,
  retryInterval: 1000,
  checkRequest: (_file: FileContext) => ({ status: CheckStatus.None }),
  mergeRequest: (_file: FileContext) => true,
  processData: (data, _processType) => data
}

drag

说明是否开启拖拽上传
类型 boolean
默认值 true

实时编辑器

function BaseExample(params) {
  const options = {
    action: 'https://tiny-uploader-server.vercel.app/file/upload',
  }

  return (
    <Uploader options={options} />
  )
}

结果

drag 值为`false`时

实时编辑器

function DragFalseExample(params) {
  return (
    <Uploader options={{
        drag: false,
        action: 'https://tiny-uploader-server.vercel.app/file/upload',
      }} 
    />
  )
}

结果

自定义上传触发节点

drag为false

实时编辑器

function Example(params) {
  return (
    <Uploader options={{
        drag: false,
        action: 'https://tiny-uploader-server.vercel.app/file/upload',
      }} 
    >
      <button>Click me !!!</button>
    </Uploader>
  )
}

结果

drag为true

实时编辑器

<Uploader options={{
    action: 'https://tiny-uploader-server.vercel.app/file/upload',
  }} 
>
  <UploadIcon size={64} style={{ transform: 'scale(0.65)' }} />
  <div className="tiny-uploader-drop_text">
    Drop file here or <em>click to upload</em>
  </div>
  <div className="tiny-uploader-drop_hint">Support for a single or bulk upload.</div>
</Uploader>

结果

accept

说明接受上传的文件类型
类型 string
默认值 *
示例-只能上传图片

实时编辑器

function AcceptExample(params) {
  return (
    <Uploader 
      options={{
        action: 'https://tiny-uploader-server.vercel.app/file/upload',
        accept: 'image/*',
      }} 
    />
  )
}

结果

multiple

说明是否支持多选文件
类型 boolean
默认值 true
示例-单文件上传

实时编辑器

function MultipleExample(params) {
  return (
    <Uploader 
      options={{
        action: 'https://tiny-uploader-server.vercel.app/file/upload',
        multiple: false,
      }} 
    />
  )
}

结果

limit

说明最大上传数量，超出会触发onExceed事件
类型 number
默认值 10
示例-最多上传一个文件

实时编辑器

function LimitExample(params) {
  return (
    <Uploader 
      options={{
        action: 'https://tiny-uploader-server.vercel.app/file/upload',
        limit: 1,
      }} 
    />
  )
}

结果

autoUpload

说明是否自动上传，触发uploader.submit方法可手动上传
类型 boolean
默认值 true
示例-不自动上传

实时编辑器

function AutoUploadExample(params) {
  return (
    <Uploader 
      options={{
        action: 'https://tiny-uploader-server.vercel.app/file/upload',
        autoUpload: false,
      }} 
    />
  )
}

结果

customGenerateUid

说明自定义生成文件唯一标识，默认使用内置id生成方法, 如果没返回也使用内置id生成方法,
类型 (file: FileContext) => void
示例-自定义生成文件唯一标识

实时编辑器

function CustomGenerateUidExample(params) {
  let uid = 0

  return (
    <Uploader 
      options={{
        action: 'https://tiny-uploader-server.vercel.app/file/upload',
        customGenerateUid: (file) => `${file.name}-${uid++}`,
      }} 
      onClick={(file) => console.log(file.uid)}
    />
  )
}

结果

beforeAdd

说明所有上传动作开始上传前的钩子, 返回false 或者返回 Promise 且被 reject 则停止上传，参数是 file，停止后会从fileList中删除，并且触发Callbacks.FileRemove回调
类型 (file: FileContext) => Promise<boolean | any> | boolean | any;
默认值 () => true
示例-校验文件大小

实时编辑器

function BeforeAddExample(params) {
  return (
    <Uploader 
      options={{
        action: 'https://tiny-uploader-server.vercel.app/file/upload',
        beforeAdd: (file) => {
          if (file.size > 1024 * 1024 * 10) {
            console.log('文件大小不能超过10MB')
            return Promise.reject('文件大小不能超过10MB')
          }
        }
      }} 
    />
  )
}

结果

beforeRemove

说明所有上传动作开始移除前的钩子, 返回false 或者返回 Promise 且被 reject 则不移除，参数是 file，移除后会从fileList中删除，并且触发Callbacks.FileRemove回调
类型 (file: FileContext) => Promise<boolean | any> | boolean | any;
默认值 () => true
示例-校验文件大小

实时编辑器

function BeforeRemoveExample(params) {
  return (
    <Uploader 
      options={{
        action: 'https://tiny-uploader-server.vercel.app/file/upload',
        beforeRemove: (file) => {
          console.log('beforeRemove', file)
          return false
        }
      }} 
    />
  )
}

结果

addFailToRemove

说明上传失败后是否自动移除文件
类型 boolean
默认值 true

chunkSize

说明分片上传的分片大小
类型 number
默认值 1024 * 1024 * 2

fakeProgress

说明是否展示上传的最大进度值（解决进度条的回退现象）。为false时,因为在某个 chunk 上传失败后，chunk 进度会变为 0，文件的进度因此会有回退抖动现象
类型 boolean
默认值 false

withHash

说明是否开启通过spark-md5生成文件的hash计算
类型 boolean
默认值 true

useWebWoker

说明计算文件hash值时使用Web Workers计算，为false时在 js 线程中计算
类型 boolean
默认值 false

危险

如果要开启useWebWoker，需要安装使用hashion的SparkWorker插件

name

上传二进制文件数据，参数名称

类型 string
默认值 file

action

上传文件的接口地址

类型 string
默认值 ''

withCredentials

类型 boolean

默认值 true

headers

上传接口携带自定义 headers

类型 object | Function

默认值 {}

data

上传接口携带自定义参数

类型 object | Function

默认值 {}

processData

处理自定义的data参数

类型 Function

默认值 (data, processType: ProcessType) => data, ProcessType

maxRetries

上传中 chunk 上传失败时的重试次数

类型 number

默认值 3

retryInterval

上传中 chunk 上传失败时的重试的间隔时间，单位是ms

类型 number

默认值 1000

maxConcurrency

上传中 chunk 最大并发数，防止过多请求

类型 number

默认值 6

requestSucceed

校验是否上传成功，根据接口定义，通过 http 的 status 或者 code 判断，参数是xhr 对象

类型 (xhr: any) => boolean

默认值

const requestSucceed = (xhr) => {
  return [200, 201, 202].includes(xhr.status)
}

备注

xhr 属性参考 -> XMLHttpRequest

示例

实时编辑器

function RequestSucceedExample(params) {
  return (
    <Uploader 
      options={{
        action: 'https://tiny-uploader-server.vercel.app/file/upload',
        requestSucceed: (xhr) => {
          const { code } = xhr.response
          return code === '00000' // 代码接口成功
        }
      }} 
    />
  )
}

结果

checkRequest

校验文件，秒传，断点续传。使用时保证withHash开启，因为校验时会用到 hash 去后端校验。参数是 file

类型 CheckRequest

默认值

实时编辑器

function CheckRequestExample(params) {
  const baseUrl = 'https://tiny-uploader-server.vercel.app/file'

  return (
    <Uploader 
      options={{
        action: `${baseUrl}/upload`,
        async checkRequest(file: FileContext) {
          const params = new URLSearchParams({
            filename: file.name,
            hash: file.hash,
            status: 'none'
          }).toString()
          const response = await fetch(`${baseUrl}/check?${params}`)
          const { data } = await response.json()
          return data
        },
      }} 
    />
  )
}

结果

备注

CheckStatus

示例

const CheckStatus = {
  Part: 'part', // 部分上传成功
  WaitMerge: 'waitMerge', // 准备合并
  Success: 'success', // 全部上传成功
  None: 'none' // 没有上传
}

const checkFileApi = (hash) => {
  // ...
}

// 情况一；默认不校验
async checkRequest(file, query, headers) {
  const hash = file.hash
  const { data } = await checkFileApi(hash)
  return { status: CheckStatus.None }
}

// 情况二；根据文件hash,文件已经上传
async checkRequest(file, query, headers) {
  const hash = file.hash
  const { data } = await checkFileApi(hash)
  return {
    status: CheckStatus.Success,
    data: 'http://baidu.com' // data是一个上传成功文件的url地址
  }
}

// 情况三；根据文件hash,文件部分上传成功
async checkRequest(file, query, headers) {
  const hash = file.hash
  const { data } = await checkFileApi(hash)
  return {
    status: CheckStatus.Part,
    data: [0, 2, 4, 6, 8, 10] // data是已经上传成功chunk的chunkIndex
  }
}

<Uploader options={{
  action: `${baseUrl}/upload`,
  checkRequest
}} />

mergeRequest

所有 chunk 上传成功之后调用的 merge 通知后端合并文件的函数, 参数 file，一般后端会返回一个文件的 obs 地址。返回false 或者返回 Promise 且被 reject则合并失败

类型 MergeRequest

默认值 const mergeRequest = (file) => true

示例

实时编辑器

function MergeRequestExample(params) {
  const baseUrl = 'https://tiny-uploader-server.vercel.app/file'

  return (
    <Uploader 
      options={{
        action: `${baseUrl}/upload`,
        mergeRequest: async (file, query, headers) => {
          const params = new URLSearchParams({
            filename: file.name,
            hash: file.hash
          }).toString()
          const response = await fetch(`${baseUrl}/merge?${params}`)
          const { data } = await response.json()
          return data
        },
      }} 
    />
  )
}

结果

customRequest

自定义上传接口, 默认为null,使用内置的request请求

类型 null | Request

默认值 null

注意

如果自定义customRequest, 需要返回一个abort方法来取消请求

示例 RequestOptions

const customRequest = (options: RequestOptions) => {
  const { action, data, query, headers, name, withCredentials, onSuccess, onFail, onProgress } =
    options
  const realData = {
    fileHashCode: data.hash,
    uploadId: data.fileId,
    chunkNumber: data.index + 1,
    chunkSize: data.size,
    totalChunks: data.totalChunks,
    [name]: data[name],
    hash: data.hash,
    filename: data.filename,
    index: data.index,
    ...query
  }
  const formData = new FormData()

  Object.keys(realData).forEach((key) => {
    formData.append(key, realData[key])
  })
  const CancelToken = axios.CancelToken
  const source = CancelToken.source()

  axios({
    url: `${BASE_URL}/upload`,
    method: 'POST',
    data: formData,
    headers: headers,
    cancelToken: source.token,
    withCredentials: withCredentials,
    onUploadProgress: onProgress
  })
    .then((response) => {
      onSuccess(action, response)
    })
    .catch((e) => {
      onFail(e)
    })

  return {
    abort() {
      source.cancel('Operation canceled by the user.')
    }
  }
}

defaultFileList​

tipRender​

options​

drag​

drag 值为false时​

自定义上传触发节点​

drag为false​

drag为true​

accept​

multiple​

limit​

autoUpload​

customGenerateUid​

beforeAdd​

beforeRemove​

addFailToRemove​

chunkSize​

fakeProgress​

withHash​

useWebWoker​

name​

action​

withCredentials​

headers​

data​

processData​

maxRetries​

retryInterval​

maxConcurrency​

requestSucceed​

checkRequest​

mergeRequest​

customRequest​

defaultFileList

tipRender

options

drag

drag 值为`false`时

自定义上传触发节点

drag为false

drag为true

accept

multiple

limit

autoUpload

customGenerateUid

beforeAdd

beforeRemove

addFailToRemove

chunkSize

fakeProgress

withHash

useWebWoker

name

action

withCredentials

headers

data

processData

maxRetries

retryInterval

maxConcurrency

requestSucceed

checkRequest

mergeRequest

customRequest