ImageUpload

qxs-image-upload 是 @qxs-bns/components 里的图片上传组件，适合头像、封面、活动头图这类需要缩略图回填、预览查看、删除和上传成功回收结果的场景。

基础用法

import '@qxs-bns/components/image-upload'

如果你已经全量引入：

import '@qxs-bns/components'

使用说明

qxs-image-upload 的主数据入口是 fileList property，推荐由宿主直接维护。
上传成功后组件会派发 upload-success，同时兼容旧版事件名 success。
如果你需要在 Vue 里模拟 v-model:file-list，可以监听 file-list-change 或 update:fileList，再回写宿主状态。

常见场景

宿主接入示例

API

属性

Name	Description	Type	Default
`action`	上传地址	`string`	`''`
`fileList`	图片列表。推荐通过 property 传入	`ImageUploadFile[]`	`[]`
`headers`	上传请求头。推荐通过 property 传入	`Record<string, string>`	`undefined`
`data`	上传时附带的额外字段。推荐通过 property 传入	`Record<string, string \| Blob>`	`undefined`
`name`	上传字段名	`string`	`'file'`
`size`	单张图片大小上限，单位 MB	`number`	`20`
`width`	缩略图宽度，单位 px	`number`	`160`
`height`	缩略图高度，单位 px	`number`	`90`
`limit`	最大上传数量	`number`	`1`
`accept`	允许上传的 MIME / 类型列表	`string`	`'image/jpeg,image/jpg,image/png,image/gif'`
`placeholder`	上传区域文案	`string`	`'上传图片'`
`notip`	是否隐藏默认提示文案	`boolean`	`false`
`tip-text`	自定义默认提示文案	`string`	`''`
`disabled`	是否禁用上传和删除	`boolean`	`false`

事件

Name	Description
`upload-success`	单张图片上传成功时触发，`detail` 包含 `response`、`file`、`files`
`success`	兼容旧版 Vue 的成功事件别名
`remove`	删除图片时触发，`detail.file` 为被删图片
`file-list-change`	图片列表变化时触发，`detail.fileList` 为当前列表
`update:fileList`	兼容旧版 `v-model:file-list` 语义的事件别名

插槽

Name	Description
`tip`	自定义底部提示内容

CSS Parts

Part	Description
`container`	外层容器
`list`	图片列表区
`item`	单张图片卡片
`image`	缩略图
`placeholder`	无图占位
`progress`	上传进度条
`actions`	悬浮操作区
`add`	新增图片入口
`add-content`	新增入口内容
`tip`	默认提示文案
`message`	校验或限制提示
`viewer`	预览弹层

常见问题

为什么上传成功后不会自动把服务端 URL 写回缩略图？

组件不会猜测你的接口响应结构。
如果你的接口返回真实图片地址，建议在 upload-success 事件里读取 detail.response，再按业务结构回写 fileList。

预览弹层和删除按钮为什么都在组件内部？

因为这两个交互是图片上传最常见的默认能力。
如果你要完全自定义宿主交互，可以只把它当成缩略图列表和上传入口，再用 part 覆盖样式。

ImageUpload ​

基础用法 ​

使用说明 ​

常见场景 ​

宿主接入示例 ​

API ​

属性 ​

事件 ​

插槽 ​

CSS Parts ​

常见问题 ​

为什么上传成功后不会自动把服务端 URL 写回缩略图？ ​

预览弹层和删除按钮为什么都在组件内部？ ​

相关文档 ​