Attachment Tray
A tray that displays a message's image and file attachments.
Usage
Basic
Loading demo...
Best Practices
- Set
removablein a composer and drop theidonremoveandcancel; keep sent messages read-only. - Give an in-flight attachment both
uploading: trueandprogress(0–1); withoutprogress, no progress shows. - Handle
open; otherwise clicking a file chip does nothing. - On non-English surfaces, override every text prop,
sizeFormatterandopenLabelFormatter, and pass the preview'slabelFormatterandzoomLabelthroughpreviewProps: the preview's buttons are icons, and these names are what screen readers announce;failedTextis visible text. - Resize thumbnails with
--tx-attachment-tray-thumb-sizerather than overriding the component's internal classes.
API Reference
TxAttachmentTray
Props
| Name | Type | Default | Description |
|---|---|---|---|
attachments | AiAttachment[] | — | Images and files in one list. Required. |
removable | boolean | false | Shows remove buttons; cancel-upload buttons don't depend on it. |
previewTitle | string | 'Preview' | The preview dialog's accessible name, followed by the image's name; also starts each thumbnail's accessible name unless openLabelFormatter builds it. |
previousLabel | string | 'Previous image' | Accessible name of the previous button. |
nextLabel | string | 'Next image' | Accessible name of the next button. |
previousText | string | — | Deprecated and not shown: the preview's previous button is an icon, named by previousLabel. |
nextText | string | — | Deprecated and not shown: the preview's next button is an icon, named by nextLabel. |
closeLabel | string | 'Close' | Accessible name of the preview's close button. |
zoomInLabel | string | 'Zoom in' | Accessible name of the preview's zoom-in button. |
zoomOutLabel | string | 'Zoom out' | Accessible name of the preview's zoom-out button. |
resetLabel | string | 'Fit to screen' | The first item of the preview's zoom menu, which shows the whole image again. |
failedText | string | 'This image could not be loaded' | Text in the preview's placeholder for an image that failed to load. |
removeLabel | string | 'Remove attachment' | Accessible name of remove buttons. |
cancelLabel | string | 'Cancel upload' | Accessible name of cancel-upload buttons. |
sizeFormatter | (bytes: number) => string | — | Formats file sizes; defaults to whole bytes under 1 KB, then KB/MB/GB with one decimal. |
openLabelFormatter | (name: string) => string | (name) => `${previewTitle}: ${name}` | Builds a thumbnail's aria-label from the image's name, or its id without one. |
previewProps | AttachmentTrayPreviewProps | — | The preview's other options, such as actions, indicator, bounce, and the materials; the tray sets the images, the failures, where they fly from, and the labels above. |
Events
| Name | Payload | Description |
|---|---|---|
remove | (id: string) | Fires when remove is clicked. |
cancel | (id: string) | Fires when cancel-upload is clicked. |
open | (attachment: AiAttachmentFile) | Fires when a file chip is clicked; clicking an image opens the built-in preview. |
action | (event: ImagePreviewActionEvent) | Fires when an action is chosen in the preview, before it runs; after preventDefault() the host runs it. |
TxAttachmentChip
Props
| Name | Type | Default | Description |
|---|---|---|---|
attachment | AiAttachment & { kind: 'file' } | — | The file attachment to show. Required. |
removable | boolean | false | Shows the remove button; the cancel-upload button doesn't depend on it. |
removeLabel | string | 'Remove attachment' | Accessible name of the remove button. |
cancelLabel | string | 'Cancel upload' | Accessible name of the cancel-upload button. |
sizeFormatter | (bytes: number) => string | — | Formats the file size; defaults to the same format as TxAttachmentTray. |
Events
| Name | Payload | Description |
|---|---|---|
remove | (id: string) | Fires when remove is clicked. |
cancel | (id: string) | Fires when cancel-upload is clicked. |
open | (attachment: AiAttachment & { kind: 'file' }) | Fires when the chip body is clicked. |
CSS Variables
| Variable | Default | Description |
|---|---|---|
--tx-attachment-tray-thumb-size | 72px | Side length of an image thumbnail. |
- The variable is not declared on the root, so setting it on the component or any ancestor takes effect.
Overview
kind: 'image'items go to the image grid andkind: 'file'items to file chips; pass both in oneattachmentsarray.- Each file renders as a
TxAttachmentChip; the tray forwardsremovable,removeLabel,cancelLabel, andsizeFormatterto it. - An
uploadingattachment always has a cancel button: images draw a progress ring, file chips show a percentage and a thin progress bar. - An image's remove or cancel button sits inside the thumbnail's top-right corner; it appears on hover or keyboard focus and stays visible on touch screens.
- Clicking an image opens it full-window in ImagePreview without emitting
open, growing it out of the thumbnail and shrinking it back on closing; the wheel, a trackpad, or two fingers zoom, a drag pans a zoomed image, a sideways swipe or ← / → turns the page at fit, and a drag up or down closes it. At either end the page button isaria-disabled, so focus never drops tobody. - Until an image arrives, the preview holds its place, shaped by the attachment's
width/heightwhen given and otherwise like the last image looked at, and shows the loading effect there once 150 ms have passed (sweep-gradientby default, set by the preview'sloadingEffect, passed throughpreviewProps). - An image that fails to load shows a placeholder icon in the thumbnail and a placeholder with
failedTextin the preview; the two share the record of failures, so the same URL is not retried, and a newurlloads again.
Technologies
- Thumbnails pin their own
imgmargin and size, so an article's typography cannot shift them; the preview is mounted on<body>, outside the article's styles. - The preview is
TxImagePreview, the same componentTxImageGalleryopens. It is loaded the first time it is about to be needed: pointing at the tray or moving focus into it starts the load, and an image pressed before it arrives opens once it does. The on-demand style plugin brings its styles with it; when importing styles by hand, also importstyle.cssfromimage-preview,base-surface,flow-light, andglass-surface. - Source:
packages/tuffex/packages/components/src/attachment-tray/.
查看源码
packages/tuffex/packages/components/src/attachment-tray/index.ts