使用 Sonner 工作
初始回應
當此技能首次被呼叫且沒有具體問題時,請僅回覆:
我已準備好協助您設定、樣式化和排解 Sonner 的問題,我的知識來自其作者 Emil Kowalski。
在用戶提出問題之前,請勿提供任何其他資訊。
這是 Sonner 吐司函式庫的技能指南。當任務涉及 Sonner — 連線設定、渲染吐司、樣式化或修復它們時,請優先從此檔案回答。<Toaster /> 和 toast() 的完整 props 表格位於 API.md;在您需要確切的 prop 名稱、類型或預設值時,請閱讀該檔案。
設定
兩個部分,而且只有兩個:
- 一個
<Toaster />,只掛載一次,盡可能靠近根目錄(在 Next.js 中:layout.tsx— 它可以在伺服器元件內運作)。切勿按頁面或有條件地渲染它;第二個掛載的 Toaster 會使每個吐司都重複顯示。 - 從客戶端程式碼呼叫
toast()— 事件處理器、副作用、回呼。它是一個純函式,不需要 hook 或 provider,但在伺服器端無效:在伺服器動作中,請回傳結果並在接收該結果的客戶端程式碼中呼叫toast()。
import { Toaster } from 'sonner'; // 一次,在 layout 中
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(),否則關閉吐司;cancel 是次要變體 |
| 自訂 JSX,使用預設吐司外殼 | toast(<jsx />) |
| 自訂 JSX,無任何樣式 | toast.custom((t) => <jsx />) — 無頭部,t 提供用於關閉的 id |
實用範例
更新吐司 — 使用相同的 id 再次呼叫 toast();只有你傳入的 props 會改變。切換到 toast.success(…, { id }) 則會改變類型。這就是無需 toast.promise 即可實現載入中 → 成功流程的方式:
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 — 為每個 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 props 替換每種類型的預設圖示,使用 icon 替換每個吐司的圖示,使用 null 移除圖示。
主題 — theme 預設為 'light' 且不會追蹤作業系統設定。請傳入 theme="system",或連線你的主題提供者:從 next-themes 使用 <Toaster theme={resolvedTheme} />。
故障排除
| 症狀 | 原因 → 修正方式 |
|---|---|
| 吐司從未出現 | 沒有掛載 <Toaster />,或它被卸載了(條件式渲染、按頁面放置)。在根目錄掛載一個。如果是從伺服器動作中呼叫:toast() 僅限客戶端 — 請在客戶端使用動作的結果來呼叫它。 |
| 同一個吐司出現兩次 | 掛載了兩個 Toaster(layout 和 page) — 保留一個。或者 toast() 在 React StrictMode 的開發模式雙重呼叫下的副作用中被觸發 — 改從事件處理器觸發,或傳入一個穩定的 id,這樣第二次呼叫會更新而非重複。 |
| Tailwind/CSS 類別無效 | 預設樣式覆蓋了它們。請加上 !important,或使用 unstyled / 無頭部模式(參見上方階梯)。 |
| 吐司渲染完全無樣式(常見於 Astro、視圖轉場) | Sonner 注入的樣式表遺失了 — 請在 layout 中明確匯入:import 'sonner/dist/styles.css'。 |
| 在 Shadow DOM 內無樣式 | 樣式被放置在 document.head,而非 shadow root 內。請將 text 包含 [data-sonner-toaster] 的 style 標籤複製到 shadow root 中。 |
| 吐司位於模態框/覆蓋層後方,或被裁切 | 上層元素建立了堆疊上下文(transform, filter, overflow)或覆蓋層的 z-index 高於 toaster。將 <Toaster /> 移到文件根目錄,放置在任何對話框/portal 容器之外。 |
| 暗色模式被忽略 | theme 預設為 'light' — 請設定 theme="system" 或傳入已解析的主題(參見上方主題說明)。 |
| 成功/錯誤看起來是灰色,而非綠色/紅色 | 這是預設值。請在 Toaster 加上 richColors。 |
| 吐司從不關閉 | duration: Infinity、dismissible: false,或 toast.promise 的 promise 從未完成 — 載入中的吐司會永遠等待。 |
toast.promise 卡在載入中 | 它需要一個 promise(或一個回傳 promise 的函式)作為第一個參數,且該 promise 必須實際 resolve/reject。 |
| 滑動關閉方向錯誤 / 無法運作 | 方向根據 position 推導。使用 Toaster 的 swipeDirections 覆蓋。 |
| 吐司出現在每個 toaster 中 | 多個 Toaster 需要定位:為每個 Toaster 指定一個 id,並在 toast() 呼叫中傳入 toasterId。 |
| 在手機上吐司太靠近螢幕邊緣 | offset(桌面,預設 32px)和 mobileOffset(<600px,預設 16px)— 數值、CSS 字串或按邊的物件。 |