Toast 轻提示
@lark-ui/core

Toast 轻提示

用于向用户展示简短、不打断操作的消息的通知系统。

import { Button, Toasty, useLarkToastManager } from "@lark-ui/core";

function ToastTriggerButton() {
  const toastManager = useLarkToastManager();

  return (
    <Button
      onClick={() =>
        toastManager.add({
          title: "轻提示已创建",
          description: "这是一条轻提示通知。",
        })
      }
    >
      显示轻提示
    </Button>
  );
}

export function ToastBasicDemo() {
  return (
    <Toasty>
      <ToastTriggerButton />
    </Toasty>
  );
}

安装

统一导出

import { Toasty, useLarkToastManager } from "@lark-ui/core";

按需导出

import { Toasty, useLarkToastManager } from "@lark-ui/core/components/toast";

用法

轻提示（Toast）系统由两部分组成：Toasty provider 组件，以及用于触发轻提示的 useLarkToastManager() hook。

import { Toasty, useLarkToastManager, Button } from "@lark-ui/core";

function ToastTrigger() {
  const toastManager = useLarkToastManager();

  return (
    <Button
      onClick={() =>
        toastManager.add({
          title: "Success!",
          description: "Your changes have been saved.",
        })
      }
    >
      Save changes
    </Button>
  );
}

export default function App() {
  return (
    <Toasty>
      <ToastTrigger />
      {/* Rest of your app */}
    </Toasty>
  );
}

初始化

用 Toasty provider 包裹你的应用（或其中的一部分）。它会建立轻提示上下文并渲染轻提示容器。

// In your app root or layout
import { Toasty } from "@lark-ui/core";

export function Layout({ children }) {
  return <Toasty>{children}</Toasty>;
}

示例

标题与描述

同时包含标题和描述的完整轻提示。

import { Button, Toasty, useLarkToastManager } from "@lark-ui/core";

function ToastTriggerButton() {
  const toastManager = useLarkToastManager();

  return (
    <Button
      onClick={() =>
        toastManager.add({
          title: "轻提示已创建",
          description: "这是一条轻提示通知。",
        })
      }
    >
      显示轻提示
    </Button>
  );
}

export function ToastBasicDemo() {
  return (
    <Toasty>
      <ToastTriggerButton />
    </Toasty>
  );
}

仅标题

只有标题的简单轻提示，用于简短消息。

import { Button, Toasty, useLarkToastManager } from "@lark-ui/core";

function ToastTitleOnlyButton() {
  const toastManager = useLarkToastManager();

  return (
    <Button
      onClick={() =>
        toastManager.add({
          title: "设置已保存",
        })
      }
    >
      仅标题
    </Button>
  );
}

export function ToastTitleOnlyDemo() {
  return (
    <Toasty>
      <ToastTitleOnlyButton />
    </Toasty>
  );
}

仅描述

只有描述的轻提示，用于更详细的消息。

import { Button, Toasty, useLarkToastManager } from "@lark-ui/core";

function ToastDescriptionOnlyButton() {
  const toastManager = useLarkToastManager();

  return (
    <Button
      onClick={() =>
        toastManager.add({
          description: "你的更改已成功保存。",
        })
      }
    >
      仅描述
    </Button>
  );
}

export function ToastDescriptionOnlyDemo() {
  return (
    <Toasty>
      <ToastDescriptionOnlyButton />
    </Toasty>
  );
}

成功变体

确认操作和正面结果请使用成功变体。

import { Button, Toasty, useLarkToastManager } from "@lark-ui/core";

/** Success toast with green accent border and check icon. */
function ToastSuccessButton() {
  const toastManager = useLarkToastManager();

  return (
    <Button
      variant="primary"
      onClick={() =>
        toastManager.add({
          title: "部署成功",
          description: "你的 Worker 已上线。",
          variant: "success",
        })
      }
    >
      部署 Worker
    </Button>
  );
}

export function ToastSuccessDemo() {
  return (
    <Toasty>
      <ToastSuccessButton />
    </Toasty>
  );
}

多个轻提示

多个轻提示会堆叠并呈现平滑的动画。悬停在堆叠上方即可展开。

import { Button, Toasty, useLarkToastManager } from "@lark-ui/core";

function ToastMultipleButton() {
  const toastManager = useLarkToastManager();

  return (
    <Button
      onClick={() => {
        toastManager.add({
          title: "第一条轻提示",
          description: "这是第一条通知。",
        });
        setTimeout(() => {
          toastManager.add({
            title: "第二条轻提示",
            description: "这是第二条通知。",
          });
        }, 500);
        setTimeout(() => {
          toastManager.add({
            title: "第三条轻提示",
            description: "这是第三条通知。",
          });
        }, 1000);
      }}
    >
      显示多条轻提示
    </Button>
  );
}

export function ToastMultipleDemo() {
  return (
    <Toasty>
      <ToastMultipleButton />
    </Toasty>
  );
}

去重轻提示

为重复的通知指定稳定的 id，屏幕上就只会保留一个轻提示。 快速连续点击：每次触发都会顶替当前轻提示，而不是再堆叠一份副本。

import { Button, Toasty, useLarkToastManager } from "@lark-ui/core";

function ToastDeduplicatedButton() {
  const toastManager = useLarkToastManager();

  return (
    <Button
      onClick={() =>
        toastManager.add({
          id: "deduplicated-toast",
          title: "连接已断开",
          description: "再次点击：这条轻提示会置顶，而不是叠加新的副本。",
        })
      }
    >
      显示相同的轻提示
    </Button>
  );
}

/** 复用固定的 ID，使重复触发只会更新同一条轻提示，而不是新增副本。 */
export function ToastDeduplicatedDemo() {
  return (
    <Toasty>
      <ToastDeduplicatedButton />
    </Toasty>
  );
}

函数式更新

基于轻提示的当前状态就地更新它。此示例会在部署提示创建后将其切换为成功状态。

import { Button, Toasty, useLarkToastManager } from "@lark-ui/core";

function ToastFunctionalUpdateButton() {
  const toastManager = useLarkToastManager();

  return (
    <Button
      onClick={() => {
        const id = toastManager.add({
          id: "functional-update",
          title: "正在部署 Worker",
          description: "正在上传你的更改。",
          variant: "info",
          data: { deployment: "进行中" },
        });

        setTimeout(() => {
          toastManager.update(id, (toast) => ({
            title: "Worker 已部署",
            description: `部署${toast.data.deployment}。`,
            variant: "success",
          }));
        }, 1200);
      }}
    >
      部署 Worker
    </Button>
  );
}

/** 演示基于当前状态更新轻提示（Toast）。 */
export function ToastFunctionalUpdateDemo() {
  return (
    <Toasty>
      <ToastFunctionalUpdateButton />
    </Toasty>
  );
}

错误变体

需要关注的关键问题请使用错误变体。

import { Button, Toasty, useLarkToastManager } from "@lark-ui/core";

function ToastErrorButton() {
  const toastManager = useLarkToastManager();

  return (
    <Button
      onClick={() =>
        toastManager.add({
          title: "部署失败",
          description: "无法连接到服务器。",
          variant: "error",
        })
      }
    >
      显示错误轻提示
    </Button>
  );
}

export function ToastErrorDemo() {
  return (
    <Toasty>
      <ToastErrorButton />
    </Toasty>
  );
}

警告变体

警示性消息请使用警告变体。

import { Button, Toasty, useLarkToastManager } from "@lark-ui/core";

function ToastWarningButton() {
  const toastManager = useLarkToastManager();

  return (
    <Button
      onClick={() =>
        toastManager.add({
          title: "速率限制警告",
          description: "你的 API 配额即将用尽。",
          variant: "warning",
        })
      }
    >
      显示警告轻提示
    </Button>
  );
}

export function ToastWarningDemo() {
  return (
    <Toasty>
      <ToastWarningButton />
    </Toasty>
  );
}

信息变体

中性的信息类消息请使用信息变体。

import { Button, Toasty, useLarkToastManager } from "@lark-ui/core";

/** Info toast with blue accent border and info icon. */
function ToastInfoButton() {
  const toastManager = useLarkToastManager();

  return (
    <Button
      onClick={() =>
        toastManager.add({
          title: "有新版本可用",
          description: "Lark v4.2 包含性能改进。",
          variant: "info",
        })
      }
    >
      显示信息轻提示
    </Button>
  );
}

export function ToastInfoDemo() {
  return (
    <Toasty>
      <ToastInfoButton />
    </Toasty>
  );
}

自定义内容

使用 content 属性可渲染完全自定义的轻提示内容。

import { Button, Toasty, useLarkToastManager, Link } from "@lark-ui/core";
import { CheckCircleIcon } from "@phosphor-icons/react/dist/ssr";

function ToastCustomContentButton() {
  const toastManager = useLarkToastManager();

  return (
    <Button
      onClick={() =>
        toastManager.add({
          content: (
            <div>
              <div className="flex items-center gap-2">
                <CheckCircleIcon />
                <Link href="/">my-first-worker</Link> 已创建！
              </div>
            </div>
          ),
        })
      }
    >
      显示自定义内容
    </Button>
  );
}

export function ToastCustomContentDemo() {
  return (
    <Toasty>
      <ToastCustomContentButton />
    </Toasty>
  );
}

操作按钮

为轻提示添加操作按钮以支持用户交互。

import { Button, Toasty, useLarkToastManager } from "@lark-ui/core";

function ToastActionsButton() {
  const toastManager = useLarkToastManager();

  return (
    <Button
      onClick={() =>
        toastManager.add({
          title: "需要帮助？",
          description: "获取部署方面的协助。",
          actions: [
            {
              children: "获取支持",
              variant: "secondary",
              onClick: () => console.log("Support clicked"),
            },
            {
              children: "询问 AI",
              variant: "primary",
              onClick: () => console.log("Ask AI clicked"),
            },
          ],
        })
      }
    >
      显示带操作按钮的轻提示
    </Button>
  );
}

export function ToastActionsDemo() {
  return (
    <Toasty>
      <ToastActionsButton />
    </Toasty>
  );
}

Promise

使用 promise 方法可以自动展示加载、成功和错误状态。

import { Button, Toasty, useLarkToastManager } from "@lark-ui/core";

function ToastPromiseButton() {
  const toastManager = useLarkToastManager();

  const simulateDeployment = () => {
    return new Promise<{ name: string }>((resolve, reject) => {
      setTimeout(() => {
        if (Math.random() > 0.3) {
          resolve({ name: "my-worker" });
        } else {
          reject(new Error("Network error"));
        }
      }, 2000);
    });
  };

  return (
    <Button
      onClick={() =>
        toastManager.promise(simulateDeployment(), {
          loading: {
            title: "正在部署……",
            description: "请稍候，我们正在部署你的 Worker。",
          },
          success: (data) => ({
            title: "部署成功！",
            description: `Worker「${data.name}」已上线。`,
          }),
          error: (err) => ({
            title: "部署失败",
            description: err.message,
            variant: "error",
          }),
        })
      }
    >
      以 Promise 方式部署
    </Button>
  );
}

export function ToastPromiseDemo() {
  return (
    <Toasty>
      <ToastPromiseButton />
    </Toasty>
  );
}

API 参考

Toasty

包裹你的应用并管理轻提示系统的 provider 组件。

属性类型默认值说明
variant"default" | "success" | "error" | "warning" | "info""default"-
children*React.ReactNode-应用内容。轻提示通过传送层渲染在其上方。
containerPortalContainer-传送层的容器元素。可用于在 Shadow DOM 或自定义容器内渲染轻提示。会覆盖 `LarkPortalProvider` 上下文。
toastManagerReturnType<typeof createLarkToastManager>-由 `createLarkToastManager()` 创建的可选轻提示管理器。提供后，React 树之外的代码（定时器、模块加载回调、查询缓存监听器）也能通过 `useLarkToastManager()` 在树内返回的同一个支持去重的管理器来触发轻提示。该属性会透传给底层的 `@base-ui/react/toast` `Toast.Provider` 的 `toastManager` 属性——上游基础组件参见 https://base-ui.com/react/components/toast。

useLarkToastManager()

返回轻提示管理器、用于创建轻提示的 hook。

const toastManager = useLarkToastManager();

// Add a toast
toastManager.add(options);

// Update from the current toast state
toastManager.update(toastId, (toast) => ({
  description: `Updated after ${toast.timeout ?? 5000}ms`,
}));

// Promise-based toast
toastManager.promise(asyncFn(), {
  loading: options,
  success: (data) => options,
  error: (err) => options,
});

轻提示选项

传给 toastManager.add() 和 promise 处理器的选项。

属性类型默认值说明
titlestring—突出显示的轻提示标题。
descriptionstring—显示在标题下方的次要文本。
variant

“default” | “success” | “error” | “warning” | “info"

"default”轻提示的视觉样式。
contentReactNode—

渲染在轻提示内部的自定义内容。会覆盖标题和描述。

actionsButtonProps[]—要渲染为操作按钮的属性数组。
timeoutnumber5000

轻提示自动消失前的毫秒数。