组件/Attachment Tray

Attachment Tray

展示图片与文件附件的消息附件区

已验证自 0.3.9

用法

基础

示例加载中...

最佳实践

  • 输入框中设置 removable,在 remove、cancel 中按 id 删除附件;已发送的消息保持只读。
  • 上传中的附件同时设置 uploading: true 与 progress(0–1);缺 progress 时不显示进度。
  • 处理 open,否则点击文件胶囊没有反应。
  • 非英文界面覆盖全部文案 prop、sizeFormatter 与 openLabelFormatter,预览的 labelFormatter 与 zoomLabel 经 previewProps 传入:预览的按钮只有图标,读屏读到的就是这些名称;failedText 是可见文字。
  • 用 --tx-attachment-tray-thumb-size 调整缩略图尺寸,不要覆盖组件内部的类名。

API 参考

TxAttachmentTray

属性

属性名类型默认值说明
attachmentsAiAttachment[]—图片与文件混合的附件列表,必填。
removablebooleanfalse显示移除按钮;取消上传按钮不受其控制。
previewTitlestring'Preview'预览对话框的可访问名称,后接图片的 name;未设 openLabelFormatter 时也是每个缩略图可访问名称的开头。
previousLabelstring'Previous image'上一张按钮的可访问名称。
nextLabelstring'Next image'下一张按钮的可访问名称。
previousTextstring—已弃用,不再显示:预览的上一张按钮只有图标,名称取 previousLabel。
nextTextstring—已弃用,不再显示:预览的下一张按钮只有图标,名称取 nextLabel。
closeLabelstring'Close'预览关闭按钮的可访问名称。
zoomInLabelstring'Zoom in'预览放大按钮的可访问名称。
zoomOutLabelstring'Zoom out'预览缩小按钮的可访问名称。
resetLabelstring'Fit to screen'预览缩放菜单的第一项,恢复整张图片。
failedTextstring'This image could not be loaded'预览图加载失败时显示在占位里的文字。
removeLabelstring'Remove attachment'移除按钮的可访问名称。
cancelLabelstring'Cancel upload'取消上传按钮的可访问名称。
sizeFormatter(bytes: number) => string—格式化文件大小;默认不足 1 KB 取整显示 B,其余 KB/MB/GB 保留一位小数。
openLabelFormatter(name: string) => string(name) => `${previewTitle}: ${name}`由图片的 name(没有时用 id)生成缩略图的 aria-label。
previewPropsAttachmentTrayPreviewProps—传给预览的其余选项,如 actions、indicator、bounce 与材质;图片、失败记录、飞出位置与上面这些文案由附件区设置。

事件

事件名参数说明
remove(id: string)点击移除时触发。
cancel(id: string)点击取消上传时触发。
open(attachment: AiAttachmentFile)点击文件胶囊时触发;点击图片打开内置的预览。
action(event: ImagePreviewActionEvent)在预览中选中操作、执行前触发;调用 preventDefault() 后由宿主执行。

TxAttachmentChip

属性

属性名类型默认值说明
attachmentAiAttachment & { kind: 'file' }—要显示的文件附件,必填。
removablebooleanfalse显示移除按钮;取消上传按钮不受其控制。
removeLabelstring'Remove attachment'移除按钮的可访问名称。
cancelLabelstring'Cancel upload'取消上传按钮的可访问名称。
sizeFormatter(bytes: number) => string—格式化文件大小;默认与 TxAttachmentTray 相同。

事件

事件名参数说明
remove(id: string)点击移除时触发。
cancel(id: string)点击取消上传时触发。
open(attachment: AiAttachment & { kind: 'file' })点击胶囊主体时触发。

CSS 变量

变量默认值说明
--tx-attachment-tray-thumb-size72px图片缩略图的边长。
  • 这个变量不在根元素上声明,写在组件或任一祖先上都会生效。

概述

  • 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