用途
本技能是 Sonner(React toast 通知库)的使用指南。当任务涉及 Sonner 的接入、渲染通知、样式调整或问题修复时,优先依据本文件回答。关于 <Toaster /> 与 toast() 的完整属性表位于 API.md,需要精确的属性名、类型或默认值时查阅该文件。
主要能力
安装与接入
Sonner 的接入只有两个部分:
- 一个 <Toaster />,只挂载一次,位置尽可能靠近根节点(在 Next.js 中为 layout.tsx,它可以在服务端组件内工作)。不要按页面渲染或条件渲染;挂载第二个 Toaster 会导致每条通知重复出现。
- 在客户端代码中调用 toast()——事件处理器、effect、回调。它是一个普通函数,不需要 hook 或 provider,但在服务端不起作用:在 server action 中应返回结果,并在接收结果的客户端代码中调用 toast()。
import { Toaster } from 'sonner'; // once, in layout
import { toast } from 'sonner'; // anywhere client-side
选择合适的调用方式
- 普通消息:toast('Title'),可加 { description } 增加第二行。
- 成功/错误/信息/警告图标:toast.success('…')、toast.error('…') 等。
- 自行管理状态时的加载指示:toast.loading('…'),之后按 id 更新。
- 加载 → 成功/错误绑定到 promise:toast.promise(promise, { loading, success, error }),success/error 可接受接收已解析值/错误的函数。
- 带操作按钮:{ action: { label, onClick } },除非 onClick 调用 event.preventDefault(),否则会关闭通知;cancel 是次要变体。
- 自定义 JSX、使用默认通知外壳:toast(<jsx />)。
- 自定义 JSX、完全无样式:toast.custom((t) => <jsx />),无头模式,t 提供用于关闭的 id。
常见用法
- 更新通知:用相同 id 再次调用 toast(),只改变传入的属性。切换为 toast.success(…, { id }) 会改变类型。这是在不使用 toast.promise 的情况下实现 loading → success 流程的方式:
const id = toast.loading('Uploading…');
toast.success('Uploaded', { id });
- 持久化:{ duration: Infinity }。关闭:toast.dismiss(id),或 toast.dismiss() 关闭全部。读取活动通知:React 中用 useSonner(),React 之外用 toast.getActiveToasts()。
- 文本中的链接或组件:为标题或描述传入函数,如 toast(() => <a href="…">View</a>)。
- 多个 toaster:为每个设置 id,并用 toast('…', { toasterId: 'canvas' }) 指定目标。不传 toasterId 时,每个 toaster 都会渲染该通知。
- 关闭回调:onDismiss 在点击关闭按钮或滑动时触发;onAutoClose 在超时时触发。两者相互独立,没有单一的“已关闭”回调。
样式:渐进方案
只在改动需要时才向上攀升;过早跳到最高层级也没问题(这是推荐的最终状态),但停留在中间层级不可取。
- 默认:在 Toaster 上加 richColors 获得彩色的成功/错误样式,invert 可反转主题。
- 内联调整:在 Toaster 上设置 toastOptions={{ style: {…} }} 作用于所有通知,或在每次 toast() 调用中设置 style。
- 为各部分添加类名:toastOptions={{ classNames: { toast, title, description, actionButton, cancelButton, closeButton } }}。Sonner 注入的样式在层叠中优先,因此每个类名都需要 !important(Tailwind:!text-red-900)。如果标记了多处 important,应停止——改用无头模式。
- 无头:使用 toast.custom() 搭配自己的 JSX,保留 Sonner 的定位、堆叠和滑动。设计系统通知的推荐做法是将其包装进自己的 toast() 抽象。(unstyled: true 是折中方案,但无头模式在同等成本下提供更多控制。)
- 图标:通过 Toaster 的 icons 属性按类型替换默认图标,通过 icon 按通知替换,用 null 移除。
- 主题:theme 默认为 'light',不跟随操作系统。传入 theme="system",或接入主题 provider:来自 next-themes 的 <Toaster theme={resolvedTheme} />。
排错
- 通知从不出现:未挂载 <Toaster />,或它被卸载(条件渲染、按页面放置)。在根节点挂载一个。如果从 server action 调用:toast() 仅限客户端——在客户端用 action 的结果调用它。
- 同一通知出现两次:挂载了两个 Toaster(layout 和 page)——保留一个。或在 React StrictMode 开发环境双重调用下在 effect 中触发 toast()——改为从事件处理器触发,或传入稳定的 id 使第二次调用更新而非重复。
- Tailwind/CSS 类名无效:默认样式覆盖了它们。标记为 !important,或使用 unstyled / 无头模式(见上文渐进方案)。
- 通知完全无样式(常见于 Astro、视图过渡):Sonner 注入的样式表丢失——在 layout 中显式导入:import 'sonner/dist/styles.css'。
- Shadow DOM 内无样式:样式落在 document.head,而非 shadow root。将文本包含 [data-sonner-toaster] 的 style 标签复制到 shadow root 中。
- 通知被模态框/浮层遮挡或被裁剪:某个祖先创建了层叠上下文(transform、filter、overflow),或浮层的 z-index 高于 toaster。将 <Toaster /> 移到文档根节点,置于任何 dialog/portal 容器之外。
- 深色模式被忽略:theme 默认为 'light'——设置 theme="system" 或传入解析后的主题(见上文主题)。
- 成功/错误显示为灰色而非绿色/红色:这是默认行为。在 Toaster 上添加 richColors。
- 通知从不关闭:duration: Infinity、dismissible: false,或 toast.promise 的 promise 永不结束——loading 通知会一直等待。
- toast.promise 卡在 loading:它需要 promise(或返回 promise 的函数)作为第一个参数,且该 promise 必须实际 resolve/reject。
- 滑动关闭方向错误或不工作:方向由 position 推导。用 Toaster 上的 swipeDirections 覆盖。
- 通知出现在每个 toaster 中:多个 toaster 需要指定目标:为每个 Toaster 设置 id,并在 toast() 调用中传入 toasterId。
- 移动端通知离屏幕边缘太近:offset(桌面端,默认 32px)和 mobileOffset(<600px,默认 16px)——可以是数字、CSS 字符串或按边设置的对象。
适用场景
适用于 React 应用(含 Next.js)中需要 toast 通知的场景,包括接入配置、选择调用方式、样式定制与问题排查。
限制
toast() 仅限客户端使用,在服务端不起作用;theme 默认不跟随系统;Sonner 注入的样式在层叠中优先,覆盖类名需要 !important;多个 Toaster 需显式指定 toasterId 才能定向。