xiaoye-components

Appearance

Upload 上传 ​

xy-upload 适合附件上传、图片上传和补充材料提交。当前版本接口完善，主绑定方式推荐使用 v-model:file-list。

何时使用 ​

  • 需要用户上传附件、文档或补充材料时，使用默认列表模式。
  • 需要图片预览和回显时，使用 list-type="picture" 或 "picture-card"。
  • 需要批量拖拽上传时，开启 drag。
  • 需要手动控制上传时机（如先选文件再统一提交）时，关闭 auto-upload 并调用 submit()。
  • 需要接入自定义上传 SDK（签名直传、网关封装等）时，使用 http-request。
  • 需要限制文件类型或数量时，使用 accept 和 limit。

何时不使用 ​

  • 需要纯图片裁剪编辑时，Upload 不提供裁剪能力，应搭配图片编辑组件使用。
  • 需要大文件分片上传时，Upload 不内置分片逻辑，需通过 http-request 自行实现。
  • 需要文件夹树形展示时，Upload 的 directory 只负责选择，不提供目录结构渲染。
  • 需要上传进度可视化看板时，Upload 的进度仅展示在文件项内，复杂场景需自行扩展。

基础用法 ​

默认模式适合普通附件上传场景，用户点击触发区后选择本地文件。

点击选择文件

支持本地文件上传

支持 png、jpg、pdf 等常见格式

拖拽上传 ​

drag 适合补充材料、附件批量提交这类更重的上传场景。

拖拽文件到此处

或点击选择文件

拖拽上传适合补充材料、附件批量提交等场景

图片列表 ​

list-type="picture" 适合封面、设计稿和截图回显。

点击选择文件

支持本地文件上传

图片列表适合头像、封面和设计稿回显。
  • 120.6 KB

图片卡片 ​

list-type="picture-card" 会把上传入口直接嵌入卡片列表末尾。

+上传

超限反馈 ​

通过 limit 和 exceed 事件，把超限文件直接反馈给用户。

点击选择文件

支持本地文件上传

尝试一次选择 3 个以上文件，可以看到超限反馈
最多保留 2 个文件。当前文件数：0

手动上传 ​

关闭 auto-upload 后，可以先把文件加入列表，再通过组件暴露的 submit() 手动发起上传。

点击选择文件

支持本地文件上传

先选中文件，再由业务按钮手动发起上传
待处理文件：0

上传前校验 ​

before-upload 返回 false 时，文件不会进入上传流程。

点击选择文件

支持本地文件上传

上传前先做业务校验，失败文件不会进入列表
请上传小于 1 MB 的文件。

自定义请求 ​

通过 http-request 可以接入自定义上传 SDK、签名直传或网关封装。

点击选择文件

支持本地文件上传

适合接入项目自己的 SDK、签名直传或网关封装
最近响应：暂无响应

自定义触发器与说明 ​

通过 trigger 和 tip 插槽，可以把上传入口接入项目自己的按钮体系。

支持 PDF、PNG、JPG，单文件不超过 10 MB。

自定义文件项 ​

file 插槽适合把文件列表渲染成更贴近业务的样式。

点击选择文件

支持本地文件上传

  • success合作协议.pdf

文件类型限制 ​

通过 accept 给出浏览器侧的文件类型过滤提示，适合合同、截图和设计稿补传场景。

拖拽文件到此处

或点击选择文件

仅接收 PDF / PNG / JPG / JPEG，用于合同、截图和设计稿补充
允许类型：PDF / PNG / JPG / JPEG当前文件数：0

目录上传 ​

directory 适合素材目录、静态资源包或批量截图目录的整体导入。

点击选择文件

支持本地文件上传

支持选择整个目录

粘贴上传与自定义预览 ​

开启 paste 后可以直接粘贴剪贴板中的文件；preview-file 适合在预览前换成自定义地址或签名图像。

+上传
支持直接粘贴截图或图片文件

编辑态回显与继续补传 ​

通过 v-model:file-list 传入现有文件列表，适合编辑态回显和继续补充上传。

点击选择文件

支持本地文件上传

预设文件列表适合编辑态回显和继续补充上传
  • 321.2 KB
  • 17.9 KB

行为约定 ​

  • 上传触发区支持 Enter / Space 打开文件选择。
  • limit 用来限制最终可保留的文件数量。
  • auto-upload="false" 时，文件会先进入 ready 状态，等待手动调用 submit()。
  • before-upload 返回 false 或 rejected Promise 时，会阻止该文件进入上传流程。
  • list-type="picture" 和 picture-card 会优先使用 url 或本地图像对象 URL 渲染缩略图。
  • directory 只影响文件选择入口，不会改变 file-list 的结构。
  • paste 只在当前上传区获得焦点或命中粘贴事件时生效。
  • 在表单中会把校验消息关联到上传触发区。

API ​

Upload Attributes ​

属性说明类型默认值
file-list当前文件列表UploadFileItem[][]
action上传地址string'#'
headers请求头UploadProps["headers"]{}
method上传方法string'post'
data额外上传参数UploadProps["data"]{}
name文件字段名string'file'
accept原生文件类型限制string''
multiple是否支持多选booleanfalse
limit最大文件数量numberundefined
disabled是否禁用booleanfalse
drag是否启用拖拽上传booleanfalse
directory是否支持目录选择booleanfalse
paste是否支持粘贴上传booleanfalse
tip上传提示文案string''
size组件尺寸UploadProps["size"]跟随全局配置
auto-upload是否自动上传booleantrue
show-file-list是否显示文件列表booleantrue
with-credentials是否携带 cookiebooleanfalse
list-type文件列表展示类型UploadListType'text'
before-upload上传前钩子UploadProps["beforeUpload"]undefined
before-remove删除前钩子UploadProps["beforeRemove"]undefined
on-change文件选择或状态变化钩子UploadProps["onChange"]undefined
on-remove删除文件钩子UploadProps["onRemove"]undefined
on-preview点击预览钩子UploadProps["onPreview"]undefined
preview-file自定义预览地址解析UploadProps["previewFile"]undefined
on-success上传成功钩子UploadProps["onSuccess"]undefined
on-progress上传进度钩子UploadProps["onProgress"]undefined
on-error上传失败钩子UploadProps["onError"]undefined
on-exceed超限钩子UploadProps["onExceed"]undefined
http-request自定义上传请求实现UploadRequestHandlerundefined

UploadFileItem ​

字段说明类型
uid文件唯一标识string
name文件名string
size文件大小number
typeMIME 类型string
status当前状态UploadStatus
percentage上传进度number
response上传响应unknown
url文件地址string
raw原始文件对象UploadRawFile

Upload Events ​

事件说明参数
update:fileList更新文件列表UploadFileItem[]

Upload Exposes ​

暴露项说明类型
submit手动上传待上传项UploadInstance["submit"]
abort取消上传UploadInstance["abort"]
clearFiles清空当前文件列表UploadInstance["clearFiles"]
handleStart手动把原始文件加入队列UploadInstance["handleStart"]
handleRemove手动移除文件项UploadInstance["handleRemove"]

Upload Slots ​

插槽说明
default默认上传区内容
trigger自定义上传触发器
tip自定义提示文案
file自定义文件项渲染