Skip to content
Lenso UI

Toast

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

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

结构变化

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

import { ToastProvider, useToast } from "@lenso/ui";
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 "@lenso/ui";
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"});

各变体的辅助方法

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

Promise 支持

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

自定义 Toast 渲染

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

总结

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