TuffNexus
|Docs
组件/Attachment Tray

Attachment Tray

消息附件区，图片走网格与预览器，文件走胶囊，可选上传进度与移除。

Verified自 0.3.9

Attachment Tray

基础用法

Attachment Tray

示例加载中...

交互契约

  • 附件按 kind 自动分流：image 进图片网格，file 进文件胶囊。两类混在同一个 attachments 数组里传入即可。
  • removable 是两种模式的开关：为真时显示移除与取消上传（输入框场景），为假时整个区域只读（消息场景）。
  • 三个事件各有分工：remove 与 cancel 携带附件 id；open 只由文件胶囊派发，携带整个附件对象，「打开」具体做什么由消费方决定。
  • 图片没有 open 事件——点击图片会打开组件内置的预览器（基于 TxModal），不需要宿主接线。
  • 预览器只在图片之间翻页，索引会被夹在有效范围内；文件不参与翻页。
  • 预览器标题优先用图片的 name，缺失时回退到 previewTitle。
  • 缩略图加载失败会被按 id 记下并换成占位块，不会显示浏览器的破图标志，也不会反复重试。
  • 上传进度由附件上的 uploading 与 progress（0~1）驱动，画成环形进度。
  • 文件大小默认按 B / KB / MB 保留一位小数，sizeFormatter 可整体接管。

API

Props

属性名类型默认值说明
attachmentsAiAttachment[]—图片与文件混合的附件列表。必填。
removablebooleanfalse是否显示移除 / 取消上传。输入框场景为真，消息场景为假。
previewTitlestring'Preview'图片无 name 时的预览器标题。
previousLabelstring'Previous image'上一张按钮的可访问名称。
nextLabelstring'Next image'下一张按钮的可访问名称。
previousTextstring'Prev'上一张按钮的可见文字。
nextTextstring'Next'下一张按钮的可见文字。
removeLabelstring'Remove attachment'移除按钮的可访问名称。
cancelLabelstring'Cancel upload'取消上传按钮的可访问名称。
sizeFormatter(bytes: number) => string—自定义文件大小文案；未设时回退到 B/KB/MB。

Events

事件名参数说明
remove(id: string)点击移除时派发。
cancel(id: string)点击取消上传时派发。
open(attachment: AiAttachmentFile)仅文件胶囊派发；图片走内置预览器。

Slots

TxAttachmentTray 不暴露插槽。图片网格与文件胶囊的结构是固定的。

最佳实践

  • 输入框里传 removable，消息里不要传——这是区分「还能改」与「已发出」的唯一信号。
  • remove 与 cancel 都只给 id，请自行按 id 从列表中剔除；组件不会自己修改 attachments。
  • 上传中的附件同时给 uploading: true 与 progress，只给其一会让环形进度停在起点。
  • 文件的 open 必须自己实现，否则点击文件胶囊没有任何反应。
  • 非英文界面需覆盖六个文案 prop 加 sizeFormatter，其中 previousText / nextText 是可见文字，漏掉最显眼。