- 输入框中设置
removable,在 remove、cancel 中按 id 删除附件;已发送的消息保持只读。 - 上传中的附件同时设置
uploading: true 与 progress(0–1);缺 progress 时不显示进度。 - 处理
open,否则点击文件胶囊没有反应。 - 非英文界面覆盖全部文案 prop、
sizeFormatter 与 openLabelFormatter,预览的 labelFormatter 与 zoomLabel 经 previewProps 传入:预览的按钮只有图标,读屏读到的就是这些名称;failedText 是可见文字。 - 用
--tx-attachment-tray-thumb-size 调整缩略图尺寸,不要覆盖组件内部的类名。
| 属性名 | 类型 | 默认值 | 说明 |
|---|
attachments | AiAttachment[] | — | 图片与文件混合的附件列表,必填。 |
removable | boolean | false | 显示移除按钮;取消上传按钮不受其控制。 |
previewTitle | string | 'Preview' | 预览对话框的可访问名称,后接图片的 name;未设 openLabelFormatter 时也是每个缩略图可访问名称的开头。 |
previousLabel | string | 'Previous image' | 上一张按钮的可访问名称。 |
nextLabel | string | 'Next image' | 下一张按钮的可访问名称。 |
previousText | string | — | 已弃用,不再显示:预览的上一张按钮只有图标,名称取 previousLabel。 |
nextText | string | — | 已弃用,不再显示:预览的下一张按钮只有图标,名称取 nextLabel。 |
closeLabel | string | 'Close' | 预览关闭按钮的可访问名称。 |
zoomInLabel | string | 'Zoom in' | 预览放大按钮的可访问名称。 |
zoomOutLabel | string | 'Zoom out' | 预览缩小按钮的可访问名称。 |
resetLabel | string | 'Fit to screen' | 预览缩放菜单的第一项,恢复整张图片。 |
failedText | string | 'This image could not be loaded' | 预览图加载失败时显示在占位里的文字。 |
removeLabel | string | 'Remove attachment' | 移除按钮的可访问名称。 |
cancelLabel | string | 'Cancel upload' | 取消上传按钮的可访问名称。 |
sizeFormatter | (bytes: number) => string | — | 格式化文件大小;默认不足 1 KB 取整显示 B,其余 KB/MB/GB 保留一位小数。 |
openLabelFormatter | (name: string) => string | (name) => `${previewTitle}: ${name}` | 由图片的 name(没有时用 id)生成缩略图的 aria-label。 |
previewProps | AttachmentTrayPreviewProps | — | 传给预览的其余选项,如 actions、indicator、bounce 与材质;图片、失败记录、飞出位置与上面这些文案由附件区设置。 |
| 事件名 | 参数 | 说明 |
|---|
remove | (id: string) | 点击移除时触发。 |
cancel | (id: string) | 点击取消上传时触发。 |
open | (attachment: AiAttachmentFile) | 点击文件胶囊时触发;点击图片打开内置的预览。 |
action | (event: ImagePreviewActionEvent) | 在预览中选中操作、执行前触发;调用 preventDefault() 后由宿主执行。 |
| 属性名 | 类型 | 默认值 | 说明 |
|---|
attachment | AiAttachment & { kind: 'file' } | — | 要显示的文件附件,必填。 |
removable | boolean | false | 显示移除按钮;取消上传按钮不受其控制。 |
removeLabel | string | 'Remove attachment' | 移除按钮的可访问名称。 |
cancelLabel | string | 'Cancel upload' | 取消上传按钮的可访问名称。 |
sizeFormatter | (bytes: number) => string | — | 格式化文件大小;默认与 TxAttachmentTray 相同。 |
| 事件名 | 参数 | 说明 |
|---|
remove | (id: string) | 点击移除时触发。 |
cancel | (id: string) | 点击取消上传时触发。 |
open | (attachment: AiAttachment & { kind: 'file' }) | 点击胶囊主体时触发。 |
| 变量 | 默认值 | 说明 |
|---|
--tx-attachment-tray-thumb-size | 72px | 图片缩略图的边长。 |
- 这个变量不在根元素上声明,写在组件或任一祖先上都会生效。
kind: 'image' 进入图片网格,kind: 'file' 进入文件胶囊;两类放在同一个 attachments 中。- 每个文件渲染为
TxAttachmentChip,Tray 向它透传 removable、removeLabel、cancelLabel 与 sizeFormatter。 uploading 为真的附件始终带取消按钮:图片绘制环形进度,文件胶囊显示百分比和一条细进度条。- 图片的移除或取消按钮在缩略图右上角内侧,悬停或键盘聚焦时出现,触屏上常显。
- 点击图片用 ImagePreview 全屏打开,不派发
open;图片从缩略图放大飞出、关闭时缩回,可用滚轮、触控板或双指缩放,放大后拖动平移,未放大时左右滑动或 ← / → 翻页,上下拖走关闭。翻到两端时翻页按钮设为 aria-disabled,焦点不会掉到 body。 - 图片到达前,预览先留出位置:附件带
width / height 时按其比例,否则沿用上一张看过的图片的比例;超过 150 ms 仍未到达才显示加载效果(默认 sweep-gradient,由预览的 loadingEffect 决定,经 previewProps 传入)。 - 图片加载失败后,缩略图显示占位图标,预览显示占位与
failedText;两边共用失败记录,同一地址不再重试,url 变化后重新加载。
- 缩略图自行固定
img 的外边距与尺寸,放进带排版样式的文章里也不会偏移;预览挂在 <body> 上,不受文章样式影响。 - 预览即
TxImagePreview,与 TxImageGallery 打开的是同一个组件。它在第一次要用时才加载:指针移到托盘上或焦点进入托盘时开始,加载完成前按下的图片在加载完成后打开。按需样式插件让它的样式随它一起加载;手动引入样式时另引 image-preview、base-surface、flow-light 与 glass-surface 的 style.css。 - 源码:
packages/tuffex/packages/components/src/attachment-tray/。
查看源码packages/tuffex/packages/components/src/attachment-tray/index.ts