上传配置（uploadConfig）

uploadConfig 配置在 config 下，全表单共用一套上传接口，所有 component='upload' 的字段均使用该配置。单个字段如需覆盖（如不同的 limit、accept），可在该 field 上单独配置 uploadConfig 覆盖全局。

配置项

属性	说明	类型	默认值
api	上传方法：(file, formData) => Promise<{ url, name? }>，返回的 url、name 会写入表单值	Function	-
limit	最大上传数量	Number	10
accept	允许的文件格式，如 .jpg,.png 或 image/*	String	-
maxSize	单文件最大体积（MB）	Number	10
headers	请求头	Object	-
data	额外上传参数	Object	-
name	上传字段名	String	'file'
triggerText	触发区文案	String	'点击上传'
listItemSize	列表项/触发区尺寸（数字为 px，如 80、120、160）	Number | String	120
httpRequest	自定义上传方法，覆盖默认请求	Function	-
responsePath / responsePaths	从上传响应中提取文件地址的字段路径，支持字符串路径或多个候选路径	String | String[]	-
successCode	判断上传响应是否成功的值，默认 1，也可传函数自定义判断逻辑	Any | Function	1
codeKey	上传响应状态码字段名	String	'code'
messageKey	上传响应消息字段名	String	'msg'
valueFormat	表单值的存储/提交格式，见下方说明	String	'array'
separator	valueFormat='string' 时多个 url 的拼接分隔符	String	','
showName	是否在缩略图底部显示文件名（渐变浮层样式，hover 时与操作按钮一起淡入；文件名支持 tooltip 显示完整名称）	Boolean	true

valueFormat — 值格式

控制上传字段在表单 model 中存储和提交给后端的格式：

值	说明	示例
'array'（默认）	对象数组 [{ url, name }, ...]	[{ url: 'http://...', name: 'a.jpg' }]
'urlArray'	纯 url 字符串数组	['http://...', 'http://...']
'string'	多个 url 用 separator 拼接为字符串	'http://...,http://...'
'url'	只取第一个 url 字符串（单图场景）	'http://...'

// 默认：对象数组
uploadConfig: { api: uploadApi }
// 提交值：[{ url: 'http://...', name: 'a.jpg' }]

// 根据响应中的 code / msg 判断上传是否成功
uploadConfig: {
  api: uploadApi,
  successCode: 0,
  codeKey: 'code',
  messageKey: 'msg'
}

// 从响应指定字段中提取 url
uploadConfig: {
  api: uploadApi,
  responsePath: 'data.url'
}

// 多个候选路径，按顺序尝试
uploadConfig: {
  api: uploadApi,
  responsePaths: ['data.url', 'result.fileUrl', 'file.url']
}

// 纯 url 数组
uploadConfig: { api: uploadApi, valueFormat: 'urlArray' }
// 提交值：['http://img1.com/a.jpg', 'http://img2.com/b.jpg']

// 逗号拼接字符串
uploadConfig: { api: uploadApi, valueFormat: 'string' }
// 提交值：'http://img1.com/a.jpg,http://img2.com/b.jpg'

// 自定义分隔符
uploadConfig: { api: uploadApi, valueFormat: 'string', separator: '|' }
// 提交值：'http://img1.com/a.jpg|http://img2.com/b.jpg'

// 单图 url 字符串（limit: 1 时推荐）
uploadConfig: { api: uploadApi, valueFormat: 'url', limit: 1 }
// 提交值：'http://img1.com/a.jpg'

回显时组件会自动根据 valueFormat 反向解析，无需手动转换。

基本用法

config: {
  uploadConfig: {
    api: async (file, formData) => {
      const form = new FormData()
      form.append('file', file)
      const res = await fetch('/api/upload', { method: 'POST', body: form }).then(r => r.json())
      return { url: res.url, name: file.name }
    },
    limit: 10,
    accept: '.jpg,.jpeg,.png,.gif',
    maxSize: 2
  },
  fields: [
    { label: '封面', key: 'cover', component: 'upload' },
    { label: '附件', key: 'files', component: 'upload' }
  ]
}

字段级覆盖

某个字段需要不同的上传限制时，可在 field 上单独配置 uploadConfig，它会覆盖表单级的同名配置：

config: {
  uploadConfig: {
    api: uploadApi,
    limit: 5,
    accept: 'image/*'
  },
  fields: [
    // 使用全局 uploadConfig
    { label: '封面', key: 'cover', component: 'upload' },
    // 覆盖：该字段只允许上传 1 个，且接受所有文件类型
    {
      label: '附件',
      key: 'attachment',
      component: 'upload',
      uploadConfig: { limit: 1, accept: '*' }
    }
  ]
}

说明

• 上传组件为虚线边框、中间加号的触发区。
• 表单值为 [{ url, name }, ...] 数组。
• 上传完成后，列表支持拖拽排序。
• 上传成功会先按 successCode / codeKey / messageKey 判断是否真正成功，再按 responsePath / responsePaths 提取文件地址。
• 上传中显示 loading 遮罩；删除前弹出确认框。
• accept 支持 image/*、video/* 及具体扩展名（如 .pdf,.docx）。