---
title: Attachment Tray
description: 展示图片与文件附件的消息附件区
category: AiChat
status: beta
since: 0.3.9
tags: [ai, attachment, upload]
syncStatus: reviewed
verified: true
---

## 用法

### 基础
::::TuffDemoWrapper{demo="AttachmentTrayAttachmentTrayDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  import type { AiAttachment, AiAttachmentFile } from '@talex-touch/tuffex/ai-elements'
  import { ref } from 'vue'

  const attachments = ref<AiAttachment[]>([
    { kind: 'image', id: 'i1', url: 'https://picsum.photos/id/1015/400/300', name: 'canyon.jpg' },
    { kind: 'image', id: 'i2', url: 'https://picsum.photos/id/1043/400/300', name: 'shore.jpg', uploading: true, progress: 0.6 },
    { kind: 'file', id: 'f1', name: 'report.pdf', size: 240_000 },
    { kind: 'file', id: 'f2', name: 'uploading.zip', size: 1_200_000, uploading: true, progress: 0.4 },
  ])

  // 组件不修改列表：移除和取消上传都由宿主按 id 删除。
  function drop(id: string) {
    attachments.value = attachments.value.filter(item => item.id !== id)
  }

  function onOpen(file: AiAttachmentFile) {
    // 打开或下载文件由宿主决定。
  }
  </script>

  <template>
    <TxAttachmentTray
      :attachments="attachments"
      removable
      @remove="drop"
      @cancel="drop"
      @open="onOpen"
    />
  </template>
---
::::

### 最佳实践

- 输入框中设置 `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

#### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `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()` 后由宿主执行。 |

### TxAttachmentChip

#### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `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' })` | 点击胶囊主体时触发。 |

### CSS 变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `--tx-attachment-tray-thumb-size` | `72px` | 图片缩略图的边长。 |

- 这个变量不在根元素上声明，写在组件或任一祖先上都会生效。

## 概述

- `kind: 'image'` 进入图片网格，`kind: 'file'` 进入文件胶囊；两类放在同一个 `attachments` 中。
- 每个文件渲染为 `TxAttachmentChip`，Tray 向它透传 `removable`、`removeLabel`、`cancelLabel` 与 `sizeFormatter`。
- `uploading` 为真的附件始终带取消按钮：图片绘制环形进度，文件胶囊显示百分比和一条细进度条。
- 图片的移除或取消按钮在缩略图右上角内侧，悬停或键盘聚焦时出现，触屏上常显。
- 点击图片用 [ImagePreview](/docs/dev/components/image-preview) 全屏打开，不派发 `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/`。

<TuffDocSourceLink />
