附件

workspace.pngPNG · 820 KB

desk-reference.jpgJPG · 1.1 MB

office-reference.jpgJPG · 940 KB

sales-dashboard.pdfUploading · 64%

message-renderer.tsxTypeScript · 12 KB

Copy

import { FileCodeIcon, XIcon } from "lucide-react"

import {

View Code

Attachment 组件用于显示文件或图片附件及其媒体、名称和元数据，并可带有可选的操作和上传状态。可将其用于聊天编辑器、消息线程和上传列表中的文件与图片。

安装#

pnpmnpmyarnbun
pnpm dlx shadcn@latest add attachment
Copy

用法#

Copyimport {
  Attachment,
  AttachmentAction,
  AttachmentActions,
  AttachmentContent,
  AttachmentDescription,
  AttachmentMedia,
  AttachmentTitle,
} from "@/components/ui/attachment"

Copy<Attachment>
  <AttachmentMedia>
    <FileTextIcon />
  </AttachmentMedia>
  <AttachmentContent>
    <AttachmentTitle>sales-dashboard.pdf</AttachmentTitle>
    <AttachmentDescription>PDF · 2.4 MB</AttachmentDescription>
  </AttachmentContent>
  <AttachmentActions>
    <AttachmentAction aria-label="移除 sales-dashboard.pdf">
      <XIcon />
    </AttachmentAction>
  </AttachmentActions>
</Attachment>

组成#

使用以下组合来构建附件：

CopyAttachment
├── AttachmentMedia
├── AttachmentContent
│   ├── AttachmentTitle
│   └── AttachmentDescription
├── AttachmentActions
│   └── AttachmentAction
└── AttachmentTrigger

使用 AttachmentGroup 将多个附件布局为可滚动的行：

CopyAttachmentGroup
├── Attachment
└── Attachment

功能#

• 通过 AttachmentMedia 支持图标和图片媒体
• 上传状态：idle、uploading、processing、error 和 done，带有内置样式，并在进行中显示闪烁效果
• 三种尺寸以及横向或纵向布局
• 全卡片的 AttachmentTrigger，可打开链接或对话框，同时操作按钮仍可独立点击
• 可滚动、带吸附效果的 AttachmentGroup，并带有边缘渐隐效果
• 通过各部分的 className 属性可自定义样式

示例#

图片#

在 AttachmentMedia 上设置 variant="image"，并在其中渲染一个 <img>。使用 orientation="vertical" 将媒体堆叠在内容上方。

workspace.pngPNG · 820 KB

desk-reference.jpgJPG · 1.1 MB

office-reference.jpgJPG · 940 KB

Copy

import { XIcon } from "lucide-react"

import {

View Code

状态#

设置 state 以反映上传生命周期。uploading 和 processing 会让标题显示闪烁效果，而 error 会切换为破坏性样式。

import {
  CheckIcon,
  ClockIcon,

尺寸#

使用 size 在 default、sm 和 xs 之间切换。

import { FileTextIcon } from "lucide-react"

import {

分组#

将附件包裹在 AttachmentGroup 中，以将它们布局为一个可水平滚动、带吸附效果的行，并带有边缘渐隐。

briefing-notes.pdfPDF · 1.4 MB

workspace.pngPNG · 820 KB

customers.csvCSV · 18 KB

renderer.tsxTSX · 12 KB

Copy

import {
  FileCodeIcon,
  FileTextIcon,

View Code

触发器#

添加 AttachmentTrigger，让整个卡片打开链接或对话框。它会填充卡片中动作按钮后方的区域，因此这些动作仍然可以点击。

import { CopyIcon, FileSearchIcon, XIcon } from "lucide-react"

import {

Copy<Dialog>
  <Attachment>
    {/* 媒体、内容、操作 */}
    <DialogTrigger asChild>
      <AttachmentTrigger aria-label="预览 research-summary.pdf" />
    </DialogTrigger>
  </Attachment>
  <DialogContent>{/* ... */}</DialogContent>
</Dialog>

无障碍#

AttachmentAction 会渲染一个 Button，而 AttachmentTrigger 会渲染一个真正的 <button>（或者通过 asChild 使用你的元素）。请遵循下面的指导，以确保它们都能被操作并被正确播报。

为仅图标操作添加标签#

AttachmentAction 通常只有图标，因此请为每个操作提供一个 aria-label，描述该操作及其目标。

Copy<AttachmentAction aria-label="移除 sales-dashboard.pdf">
  <XIcon />
</AttachmentAction>

为触发器添加标签#

AttachmentTrigger 会在没有自身文字内容的情况下覆盖卡片，因此请为它添加一个 aria-label，说明激活它会执行什么操作。

Copy<AttachmentTrigger asChild>
  <a
    href={url}
    target="_blank"
    rel="noreferrer"
    aria-label="打开 workspace.png"
  />
</AttachmentTrigger>

触发器位于堆叠顺序中操作按钮的后面，因此 AttachmentAction 和 AttachmentTrigger 不会互相阻挡——两者仍然可以分别聚焦和点击。

键盘滚动#

AttachmentGroup 会水平滚动。当其中的附件具有交互性时：触发器或操作按钮，键盘用户可以通过 Tab 键切换到屏幕外的项目。对于仅展示用途的一排附件，可以通过添加 tabIndex={0}、role="group" 和 aria-label 让该组本身也可聚焦并可滚动。

不仅仅依赖颜色传达含义#

error 状态使用的是危险色。请将失败原因保留在 AttachmentDescription 中，这样该状态就不会只通过颜色来传达。

API 参考#

Attachment#

根附件容器。

AttachmentMedia#

用于图标或图片预览的媒体槽位。

AttachmentContent#

包裹标题和描述。

AttachmentTitle#

附件名称。当附件处于 uploading 或 processing 状态时会显示闪烁效果。

AttachmentDescription#

文件类型、大小或上传状态等次要元数据。

AttachmentActions#

一个或多个操作的容器，右对齐到附件末尾。

AttachmentAction#

一个操作按钮。渲染为 Button，并接受其全部属性。

AttachmentTrigger#

覆盖整张卡片、用于激活附件的叠加层。默认渲染为 <button>。

AttachmentGroup#

以可水平滚动、可吸附的行布局排列附件。