完整的 API 参考、样式指南与高级示例请参阅 v3 Toast 文档。本指南只关注从 HeroUI v2 的迁移。

结构变化

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

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() 函数：

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

const { toast } = useToast();

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

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

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

各变体的辅助方法

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" });

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

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

Promise 支持

const { toast } = useToast();

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

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

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

自定义 Toast 渲染

const { toast } = useToast();

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

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 支持与队列管理

Toast

本页目录