使用 Sonner
初始响应
当首次调用此技能且没有具体问题时,仅回复:
我已准备好帮助您设置、样式化和排查 Sonner 问题,我的知识来自其作者 Emil Kowalski。
在用户提出问题之前,不要提供任何其他信息。
这是一份针对 Sonner(Toast 库)的指南技能。当任务涉及 Sonner——连接它、渲染 Toast、设置样式或修复问题——时,优先根据此文件回答。<Toaster /> 和 toast() 的完整属性表格位于 API.md 中;当您需要确切的属性名、类型或默认值时,请阅读该文件。
设置
只需两部分,且仅此两部分:
- 一个
<Toaster />,只挂载一次,尽可能靠近根节点(在 Next.js 中:layout.tsx——它能在服务端组件内工作)。切勿按页面或有条件地渲染它;挂载第二个 Toaster 会导致每条 Toast 重复显示。 - 从客户端代码调用
toast()——事件处理程序、副作用、回调函数。它是一个普通函数,不需要 Hook 或 Provider,但在服务端上不起作用:在服务端操作中,返回结果并在接收它的客户端代码中调用toast()。
import { Toaster } from 'sonner'; // 一次,在布局中
import { toast } from 'sonner'; // 任何客户端位置
选择合适的调用
| 你想要的 | 调用方式 |
|---|---|
| 普通消息 | 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(),否则会关闭 Toast;cancel 是次要变体 |
| 自定义 JSX,使用默认 Toast 外壳 | toast(<jsx />) |
| 自定义 JSX,无任何样式 | toast.custom((t) => <jsx />)——无头模式,t 提供用于关闭的 id |
使用技巧
更新 Toast——使用相同的 id 再次调用 toast();仅传入的 props 会发生变化。切换到 toast.success(…, { id }) 会更改类型。这是在不使用 toast.promise 的情况下实现加载 → 成功流程的方法:
const id = toast.loading('上传中…');
toast.success('已上传', { id });
持久化——{ duration: Infinity }。关闭——toast.dismiss(id),或 toast.dismiss() 关闭所有。读取活跃的 Toast——在 React 中使用 useSonner(),在外部使用 toast.getActiveToasts()。
在文本中嵌入链接或组件——为标题或描述传递一个函数:toast(() => <a href="…">查看</a>)。
多个 Toaster——为每个 Toaster 指定 id,并通过 toast('…', { toasterId: 'canvas' }) 定位。如果没有 toasterId,每个 Toaster 都会渲染该 Toast。
关闭回调——onDismiss 在点击关闭按钮或滑动时触发;onAutoClose 在超时时触发。它们是分开的;不存在单一的“已关闭”回调。
样式——升级阶梯
仅按所需的程度升级;过早跳到最高等级是可以的(这是推荐的最终状态),但停留在中间等级则不可取。
- 默认样式——加上 Toaster 的
richColors可实现多彩的成功/错误提示,invert可根据主题翻转颜色。 - 内联调整——在 Toaster 上使用
toastOptions={{ style: {…} }}可应用于所有 Toast,或在每个toast()调用中使用style。 - 各部分类名——
toastOptions={{ classNames: { toast, title, description, actionButton, cancelButton, closeButton } }}。Sonner 注入的样式在级联中优先级更高,因此每个类都需要!important(Tailwind:!text-red-900)。如果您对多个属性使用了 important,请停止——改用无头模式。 - 无头模式——使用
toast.custom()搭配您自己的 JSX,保留 Sonner 的定位、堆叠和滑动功能。这是设计系统 Toast 的推荐方法:将其封装在您自己的toast()抽象中。(unstyled: true可作为中间方案,但无头模式以同样的工作量提供了更多控制权。)
图标——通过 Toaster 的 icons 属性按类型替换默认图标,通过 icon 按 Toast 替换,设置为 null 可移除。
主题——theme 默认为 'light',不会跟随操作系统。传递 theme="system",或连接您的主题提供者:通过 next-themes 使用 <Toaster theme={resolvedTheme} />。
故障排除
| 症状 | 原因 → 修复 |
|---|---|
| Toast 从不出现 | 未挂载 <Toaster />,或它被卸载了(条件渲染、按页面放置)。在根节点挂载一个。如果从服务端操作中调用:toast() 是客户端专用的——在客户端使用操作结果调用它。 |
| 同一条 Toast 出现两次 | 挂载了两个 Toaster(布局 和 页面)——保留一个。或者 toast() 在 React StrictMode 的开发模式双重调用中于副作用内触发——改为从事件处理程序触发,或传递一个固定的 id,以便第二次调用更新而非重复。 |
| Tailwind/CSS 类无效 | 默认样式覆盖了它们。将它们标记为 !important,或使用 unstyled / 无头模式(参见上面的阶梯)。 |
| Toast 完全无样式(常见于 Astro、视图过渡) | Sonner 注入的样式表丢失了——在布局中显式导入:import 'sonner/dist/styles.css'。 |
| 在 Shadow DOM 内无样式 | 样式最终位于 document.head 中,而非 Shadow 根节点。将文本包含 [data-sonner-toaster] 的 style 标签复制到 Shadow 根节点中。 |
| Toast 被模态框/覆盖层遮挡,或被裁剪 | 某个祖先元素创建了层叠上下文(transform、filter、overflow),或者覆盖层的 z-index 高于 Toaster。将 <Toaster /> 移动到文档根节点,任何对话框/门户容器之外。 |
| 深色模式被忽略 | theme 默认为 'light'——设置为 theme="system" 或传递已解析的主题(参见上面的主题部分)。 |
| 成功/错误显示为灰色,而非绿色/红色 | 这是默认状态。向 Toaster 添加 richColors。 |
| Toast 从不关闭 | duration: Infinity、dismissible: false,或 toast.promise 的 Promise 从未结算——加载 Toast 会一直等待。 |
toast.promise 卡在加载状态 | 它需要一个 Promise(或返回 Promise 的函数)作为第一个参数,并且该 Promise 必须实际 resolve/reject。 |
| 滑动关闭方向错误/不起作用 | 方向由 position 决定。通过 Toaster 的 swipeDirections 覆盖。 |
| Toast 在每个 Toaster 中都出现 | 多个 Toaster 需要定位:为每个 Toaster 指定 id,并在 toast() 调用中传递 toasterId。 |
| 在移动设备上 Toast 离屏幕边缘太近 | offset(桌面端,默认 32px)和 mobileOffset(<600px,默认 16px)——可以是数字、CSS 字符串或按边的对象。 |