xtf-upload

组件说明

xtf-upload 是文件选择、预览与上传队列组件，适用于图片、视频、附件和目录上传。支持模拟/真实上传、分片、进度、重试和拖放。

---

基础用法

1. 图片上传

<template><xtf-upload v-model="files" :max="3" @change="changed" /></template>
<script>
export default {
  data() {
    return { files: [] }
  },
  methods: {
    changed(files) {
      console.log(files)
    }
  }
}
</script>

2. 字段附件

<template>
  <xtf-upload
    v-model="files"
    variant="field"
    file-type="file"
    label="营业资质"
    picker-text="上传附件"
    :max="2"
    :preview="false"
  />
</template>
<script>
export default {
  data() {
    return { files: [] }
  }
}
</script>

3. 自定义请求

<template>
  <xtf-upload
    ref="upload"
    v-model="files"
    :mock-upload="false"
    :custom-request="request"
    :auto-upload="false"
    @progress="progress"
  />
</template>
<script>
export default {
  data() {
    return { files: [] }
  },
  methods: {
    request({ onProgress, onSuccess }) {
      onProgress(100)
      onSuccess({ data: { url: 'https://example.com/a.png' } })
    },
    progress(p) {
      console.log(p.percent)
    }
  }
}
</script>

---

全部属性

属性	类型	默认值	作用描述	适用范围
value	Array	[]	文件列表，使用 v-model	数据
max / multiple / deletable	Number/Boolean/Boolean	9/true/true	上限、多选、删除	基础交互
fileType / maxSize / sourceType / accept	String/String | Number/Array/String	'image'/0/[]/''	类型、大小、来源和接受规则	文件校验
pickerHint / pickerText / label / placeholder	String	''	文案	字段展示
readonly / required	Boolean	false	只读、必填标记	表单
variant / columns / radius / accentColor / preview	String/String | Number/String | Number/String/Boolean	'default'/3/''/''/true	布局与预览	展示
beforeUpload / beforeRead	Function	null	(file) => Boolean | Promise<Boolean>	上传前拦截
afterRead	Function	null	(file) => void	读取后处理
mockUpload / concurrent	Boolean/String | Number	true/2	模拟上传和并发数	队列
action / name / headers / formData / method / withCredentials	String/String/Object/Object/String/Boolean	''/'file'/{}/{}/'POST'/false	原生请求配置	真实上传
autoUpload / cancelable	Boolean	true/true	自动上传、允许取消	队列
onSuccess / onError / onProgress / onExceed / onOversize	Function	null	对应回调钩子	兼容回调
compress / resultKey / responseAdapter	Boolean | Object/String/Function	false/'url'/null	压缩、响应 URL 字段、(data,response,file)=>String|Object	真实上传
retryStrategy / retryLimit / retryDelay / preserveResponse	String/String | Number/String | Number/Boolean	'manual'/0/240/true	重试及响应保留	异常处理
drag / directory / chunk / chunkSize	Boolean/Boolean/Boolean/String | Number	false/false/false/1048576	拖放、目录、分片	H5
customRequest / presign / hash	Function/Function/Boolean | String	null/null/false	自定义请求、预签名、hash	高级上传
customClass / customStyle	String/String | Object	''	样式覆盖	样式

文件项数据结构

字段	类型	默认值	说明
id,name,url,type,size,status,progress	String | Number	-	文件标识、名称、地址、类型、大小、状态、进度
errorText,retryCount,hash,responseData,serverMeta,relativePath	String | Number | Object	-	错误、重试、摘要、响应及目录信息

---

事件

事件名称	回调参数	说明
input / change	(files: Array)	文件列表变化时触发。
remove / preview	({ index, item })	删除或预览文件时触发；清空时 remove 参数含 cleared: true。
before-add	({ file, accepted, reason? })	文件校验或上传前钩子处理后触发。
choose / exceed / oversize	选择器结果 / 超限详情 / ({ file })	选择文件、数量超限或文件过大时触发。
success / error / progress / cancel / retry	上传结果详情	真实、模拟或自定义请求的上传状态。
retry-all	({ count, files })	调用 retryFailed() 后触发。
drop / drag-over / drag-leave	拖放详情或原始事件	H5 拖放交互事件。
hash-ready / hash-error	({ file, hash, algorithm }) / ({ file, algorithm, error })	启用 hash 后的计算结果。

事件使用示例

<template>
  <xtf-upload
    v-model="files"
    :max-size="1024 * 1024"
    @before-add="before"
    @oversize="oversize"
    @success="success"
  />
</template>
<script>
export default {
  data() {
    return { files: [] }
  },
  methods: {
    before(p) {
      console.log('before', p.accepted)
    },
    oversize(p) {
      uni.showToast({ title: p.file.name + ' 过大', icon: 'none' })
    },
    success(p) {
      console.log('success', p.file.url)
    }
  }
}
</script>

---

方法

方法	参数	返回值	说明
chooseFiles()	无	void	打开当前 fileType 对应的文件选择器。
submit()	无	void	在真实上传模式且 autoUpload 为假时启动队列。
cancelUpload(fileId)	fileId: String	void	取消指定上传任务。
cancelAllUpload()	无	void	取消全部进行中的上传任务。
clearFiles()	无	void	取消任务、清空文件列表并触发 remove。
retryFile(file)	file: FileItem	void	重新上传指定错误文件。
retryFailed()	无	Number	重试全部错误文件，返回参与重试的数量。

submit() 示例

this.$refs.upload.submit()

cancelUpload(fileId) / cancelAllUpload() 示例

this.$refs.upload.cancelUpload('upload-1')
this.$refs.upload.cancelAllUpload()

retryFailed() 示例

console.log(this.$refs.upload.retryFailed())

---

插槽

组件源码未声明插槽；文件项、选择区域和上传状态均由属性与事件配置。

---

主题说明

• 强调色为 --xtf-upload-accent，柔和背景为 --xtf-upload-accent-soft。
• 圆角为 --xtf-upload-radius，默认继承 --xtf-radius-lg。
• 在 xtf-config-provider 或主题配置中覆盖这些变量即可全局定制。