# Toast · HeroUI

> Toast 从 HeroUI v2 到 v3 的迁移指南。

- 页面: https://jiguang132.com/zh/systems/heroui/docs/migration/toast
- 改编自: HeroUI 文档 (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af

> 
  完整的 API 参考、样式指南与高级示例请参阅 [v3 Toast 文档](/systems/heroui/docs/components/toast)。本指南只关注从 HeroUI v2 的迁移。


## 结构变化

在 v2 中，Toast 采用 Provider + Hook 模式：

```tsx
import { ToastProvider, useToast } from "@heroui/react";

function App() {
  return (
    <ToastProvider>
      <MyComponent />
    </ToastProvider>
  );
}

function MyComponent() {
  const { toast } = useToast();

  return (
    <button onClick={() => toast.show("Hello!")}>
      Show Toast
    </button>
  );
}
```

在 v3 中，Toast 改为 Provider 组件 + 全局 `toast()` 函数：

```tsx
import { Toast } from "@heroui/react";

function App() {
  return (
    <>
      <Toast.Provider />
      <MyComponent />
    </>
  );
}

function MyComponent() {
  return (
    <button onClick={() => toast("Hello!")}>
      Show Toast
    </button>
  );
}
```

## 主要变化

### 1. Provider 模式

**v2：** 必须使用 `ToastProvider` 包裹  
**v3：** 改用 `Toast.Provider` 组件（可放置在任意位置）

### 2. Hook → 函数

**v2：** 使用 `useToast()` Hook  
**v3：** 直接调用 `toast()` 函数

### 3. API 变更

**v2：** 使用 `toast.show()` 方法  
**v3：** `toast()` 是带有辅助方法的函数（`toast.success()`、`toast.danger()` 等）

### 4. 变体名称

**v2：** 变体如 `success`、`error`、`warning`、`info`  
**v3：** 变体：`default`、`accent`、`success`、`warning`、`danger`

### 5. 复合组件结构

**v3：** Toast 通过复合组件支持自定义渲染：
- `Toast` —— Toast 主容器
- `Toast.Content` —— 内容包装器
- `Toast.Title` —— 标题文字
- `Toast.Description` —— 描述文字
- `Toast.Indicator` —— 图标 / 指示器
- `Toast.CloseButton` —— 关闭按钮
- `Toast.ActionButton` —— 操作按钮

### 6. Promise 支持

**v3：** 内置 `toast.promise()` 方法，可处理异步操作

## 迁移示例

### 带标题与描述的 Toast


  

#### v2


    ```tsx
    const { toast } = useToast();

    toast.show({
      title: "Success",
      description: "Your changes have been saved",
      variant: "success"
    });
    ```
  
  

#### v3


    ```tsx
    import { toast } from "@heroui/react";

    toast.success("Success", {
      description: "Your changes have been saved"
    });
    ```
  


### 各变体的辅助方法


  

#### v2


    ```tsx
    const { toast } = useToast();

    toast.show({ variant: "success", title: "Success" });
    toast.show({ variant: "error", title: "Error" });
    toast.show({ variant: "warning", title: "Warning" });
    toast.show({ variant: "info", title: "Info" });
    ```
  
  

#### v3


    ```tsx
    import { toast } from "@heroui/react";

    toast.success("Success");
    toast.danger("Error");
    toast.warning("Warning");
    toast.info("Info");
    ```
  


### Promise 支持


  

#### v2


    ```tsx
    const { toast } = useToast();

    const handleAsync = async () => {
      try {
        await someAsyncOperation();
        toast.show({ title: "Success", variant: "success" });
      } catch {
        toast.show({ title: "Error", variant: "error" });
      }
    };
    ```
  
  

#### v3


    ```tsx
    import { toast } from "@heroui/react";

    const handleAsync = async () => {
      toast.promise(someAsyncOperation(), {
        loading: "Processing...",
        success: "Operation completed!",
        error: "Operation failed"
      });
    };
    ```
  


### 自定义 Toast 渲染


  

#### v2


    ```tsx
    const { toast } = useToast();

    toast.show({
      title: "Custom",
      render: (toast) => (
        <div>Custom content</div>
      )
    });
    ```
  
  

#### v3


    ```tsx
    import { Toast, ToastContent, ToastTitle } from "@heroui/react";

    <Toast.Provider>
      {({ toast: toastItem }) => (
        <Toast toast={toastItem}>
          <ToastContent>
            <ToastTitle>Custom content</ToastTitle>
          </ToastContent>
        </Toast>
      )}
    </Toast.Provider>
    ```
  


## 总结

- 用 `Toast.Provider` 取代 `ToastProvider`
- 用 `toast()` 函数取代 `useToast()` Hook
- 更新变体名称（`error` → `danger`、`info` → `accent`）
- 使用辅助方法：`toast.success()`、`toast.danger()` 等
- 用 `toast.promise()` 处理异步操作
- 通过复合组件结构实现自定义渲染
- 更好的 TypeScript 支持与队列管理

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt