AiAttachments 附件

用于展示一组附件信息集合，支持点击上传、拖拽上传与删除，可与 AiFileCard 搭配展示文件卡片。

何时使用

当需要展示一组附件信息（如上传中、已上传、失败状态）并支持增删时使用，常见于 AI 输入区、表单附件等场景。

基础用法

通过 v-model:items 绑定附件列表，支持点击上传与删除。列表采用遍历方式渲染，超过 2 个时逐项展示；删除需在 @delete-card 中从 items 移除对应项（如 items.value.splice(index, 1)）以生效。图标与文案采用紧凑统一风格；标题过长时自动省略，悬停可查看完整名称。

基础用法

占位信息

通过 placeholder 配置上传区域的图标、标题与描述（支持对象、函数或字符串简写）。

占位信息

拖拽上传

将文件拖拽到上传区域即可上传，可通过 getDropContainer 指定拖拽生效的容器（默认组件根节点）。

拖拽上传

删除

每张卡片悬停时显示删除按钮，点击触发 delete-card 事件。删除功能需在回调中从列表移除该项（如 onDelete(_, index) { items.value.splice(index, 1) }）方可生效；也可在回调内做二次确认或同步后端。

删除

多种状态示例

附件项支持 status：uploading（显示进度条）、done（已完成）、error（红框 + 错误文案）。可通过 percent、error、description 展示进度与说明。

多种状态

溢出模式

通过 overflow 控制列表布局：scrollX（横向滚动）、scrollY（纵向滚动）、wrap（换行）。下面用固定宽高容器分别展示三种溢出效果。

横向滚动 scrollX

纵向滚动 scrollY

换行 wrap

上传功能

基础使用

组件内置了完整的上传流程，点击上传按钮或拖拽文件到上传区域即可触发上传。组件会自动：

1. 创建文件列表项（状态为 uploading）
2. 触发 upload-change 事件
3. 调用自定义上传函数 httpRequest（如有）
4. 上传成功后更新状态为 done，触发 upload-success
5. 上传失败后更新状态为 error，触发 upload-error

基础使用

自定义上传

通过 httpRequest prop 完全自定义上传逻辑（如自定义请求头、URL、FormData 处理等）。函数接收 { file: File } 参数，需返回 Promise。

自定义上传

通过事件监听上传状态

事件监听

API

Props

属性	说明	类型	默认值
items	附件列表	AttachmentItem[]	[]
overflow	溢出模式	'wrap' | 'scrollX' | 'scrollY'	'scrollX'
scrollMaxHeight	scrollY 时容器最大高度（如 260px）	string	-
hideUpload	是否隐藏上传按钮	boolean	false
disabled	是否禁用	boolean	false
maxCount	最大文件数量	number	-
limit	文件数量限制（与 maxCount 作用相同）	number	-
placeholder	占位内容（支持对象、函数或字符串简写）	PlaceholderType | ((mode) => PlaceholderType) | string	-
getDropContainer	返回拖拽生效的容器元素，不传则使用组件根节点	() => HTMLElement	-
beforeUpload	上传前校验函数，返回 false 可取消本次上传	(file: File) => boolean | Promise<boolean>	-
httpRequest	自定义上传请求函数	(options: { file: File }) => Promise<void>	-
uploadIconSize	上传按钮图标尺寸	string	'24px'
dragTarget	拖拽目标元素	string | HTMLElement	-
listStyle	列表容器样式	Record<string, string>	{}
themeOverrides	主题覆盖变量	Record<string, unknown>	-

AttachmentItem 额外属性

除 FileCardListItem 的属性外，附件项还支持以下属性：

属性	说明	类型	默认值
status	文件状态	'uploading' | 'done' | 'error' | 'removed'	-
percent	上传进度（0-100）	number	-
response	上传成功后的响应数据	unknown	-
error	错误信息	string	-

Events

事件名	说明	参数
update:items	列表更新时触发	(items: AttachmentItem[])
upload-change	文件选择/拖拽后触发	(file: File, fileList: AttachmentItem[])
upload-success	上传成功后触发	(response: unknown, file: File, fileList: AttachmentItem[])
upload-error	上传失败后触发	(error: unknown, file: File, fileList: AttachmentItem[])
upload-drop	拖拽释放时触发	(files: File[])
delete-card	删除某一项时触发	(item: AttachmentItem, index: number)
exceed	超出文件数量限制时触发	({ files, maxCount })

Slots

插槽名	说明
default	整个组件容器内容
file-item	自定义文件卡片项内容，参数: { item: AttachmentItem, index: number }
upload-button	自定义上传按钮内容，参数: { canUpload: boolean }
drop-area	自定义拖拽区域内容