Toast - Heroui — ContextQMD

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

结构变化

在 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

<Tabs items={["v2", "v3"]}> <Tab value="v2"> ```tsx const { toast } = useToast();

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

</Tab> <Tab value="v3"> ```tsx import { toast } from "@heroui/react";

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

</Tab> </Tabs>

各变体的辅助方法

<Tabs items={["v2", "v3"]}> <Tab value="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" });
```

</Tab> <Tab value="v3"> ```tsx import { toast } from "@heroui/react";

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

</Tab> </Tabs>

Promise 支持

<Tabs items={["v2", "v3"]}> <Tab value="v2"> ```tsx const { toast } = useToast();

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

</Tab> <Tab value="v3"> ```tsx import { toast } from "@heroui/react";

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

</Tab> </Tabs>

自定义 Toast 渲染

<Tabs items={["v2", "v3"]}> <Tab value="v2"> ```tsx const { toast } = useToast();

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

</Tab> <Tab value="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>
```

</Tab> </Tabs>

总结

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