---
title: 反馈与消息
description: 配置 Toast，并用 Message、Bubble、Attachment 和 MessageScroller 组合消息界面。
order: 13
toc:
  - id: toast-provider
    title: Toast Provider
  - id: send-toast
    title: 发送 Toast
  - id: message-composition
    title: 消息组合
  - id: attachments
    title: 附件状态
  - id: scrolling
    title: 消息滚动
---

## Toast Provider {#toast-provider}

在应用根节点附近挂载一次 `Toaster`：

```tsx
import { Toaster } from "@workspace/ui/components/toast"

export function App() {
  return (
    <>
      <Routes />
      <Toaster />
    </>
  )
}
```

默认 viewport 固定在小屏底部与大屏右下角。Toast 支持堆叠、展开、滑动退出、键盘焦点和 `success`、`info`、`warning`、`error`、`loading` 类型图标。

## 发送 Toast {#send-toast}

使用模块导出的 manager：

```tsx
import { Button } from "@workspace/ui/components/button"
import { toast } from "@workspace/ui/components/toast"

;<Button
  onClick={() =>
    toast.add({
      title: "已保存",
      description: "个人资料已经更新。",
      type: "success",
    })
  }
>
  保存
</Button>
```

需要隔离通知区域时，用 `createToastManager()` 创建 manager，并同时传给 `Toaster` 与调用方。关闭按钮的默认可访问名称来自 UI 本地化上下文。

## 消息组合 {#message-composition}

```tsx
import {
  Message,
  MessageContent,
  MessageFooter,
  MessageGroup,
} from "@workspace/ui/components/message"
import { Bubble, BubbleContent } from "@workspace/ui/components/bubble"

;<MessageGroup>
  <Message align="end">
    <MessageContent>
      <Bubble align="end" variant="tinted">
        <BubbleContent>明天下午三点可以。</BubbleContent>
      </Bubble>
      <MessageFooter>已读 · 14:32</MessageFooter>
    </MessageContent>
  </Message>
</MessageGroup>
```

把消息 ID、作者、发送状态与操作保留在业务层。UI primitives 只从 props 和 `data-*` 状态决定布局。

## 附件状态 {#attachments}

`Attachment` 支持 `idle`、`uploading`、`processing`、`error` 和 `done`。`AttachmentMedia`、`AttachmentTitle`、`AttachmentDescription` 与 `AttachmentActions` 会根据状态调整外观；上传进度和重试逻辑仍由应用负责。

横向附件使用默认 `orientation="horizontal"`，缩略图网格可使用 `orientation="vertical"`。多个附件放入 `AttachmentGroup` 后会获得横向滚动和 snap 行为。

## 消息滚动 {#scrolling}

`MessageScrollerProvider`、`MessageScroller`、`MessageScrollerViewport` 与 `MessageScrollerContent` 应保持层级。每条消息放在 `MessageScrollerItem` 中；需要作为自动跟随目标的项传 `scrollAnchor`。`MessageScrollerButton direction="end"` 会根据当前可滚动状态自动显示或隐藏。

业务层追加消息时不要直接设置 `scrollTop`。使用这些 primitives 提供的 follow 和 visibility 状态，避免用户向上阅读历史内容时被强制拉回底部。