SwToast

SwToast 是全域通知元件，需要在 app.vue 或版面配置檔案的根層放置一次，由 useToast() composable 命令式觸發，無需每個頁面重複引入。

安裝與配置

<!-- app.vue -->
<template>
  <NuxtLayout><NuxtPage /></NuxtLayout>
  <SwToast />
</template>

SwToast 元件無需任何屬性，它會自動監聽 useToast() 的狀態並渲染所有活動通知。

基本用法

在任意元件中呼叫 useToast() 獲取實例，然後使用快捷方法觸發對應類型的通知：

const toast = useToast()

toast.success('檔案儲存成功')
toast.error('請求失敗，請重試')
toast.warning('磁碟空間不足 10%')
toast.info('發現新版本可供更新')

加载中...

自訂標題與時長

使用 toast.add() 可以同時指定標題、類型和自動關閉時長。將 duration 設為 0 則通知不會自動關閉，需使用者手動點擊關閉按鈕。

toast.add({
  type: 'success',
  title: '部署完成',
  message: '應用程式已成功部署到生產環境。',
  duration: 5000, // 5 秒後自動關閉
})

// 不自動關閉
toast.info('有待處理的審核任務', { duration: 0 })

加载中...

useToast() 回傳值

名稱	類型	說明
`toasts`	`ToastItem[]`	當前所有活動的通知列表（響應式）
`add`	`(options: ToastOptions) => void`	新增一條通知
`remove`	`(id: string) => void`	手動移除指定 id 的通知
`success`	`(message: string, opts?) => void`	快捷方法：顯示成功類型通知
`error`	`(message: string, opts?) => void`	快捷方法：顯示錯誤類型通知
`warning`	`(message: string, opts?) => void`	快捷方法：顯示警告類型通知
`info`	`(message: string, opts?) => void`	快捷方法：顯示資訊類型通知

add() 參數（ToastOptions）

名稱	類型	必填	預設值	說明
`message`	`string`	✓	—	通知正文內容
`title`	`string`		—	可選標題，顯示在正文上方
`type`	`'success' \| 'error' \| 'warning' \| 'info'`		`'info'`	通知類型，決定圖示和顏色風格
`duration`	`number`		`3000`	自動關閉時間（毫秒），`0` 表示不自動關閉

注意事項

<SwToast /> 必須在 app.vue 根層掛一次，否則 useToast() 靜默無效（Rule STO-001）—— useToast().success() 只往全域佇列 push，真正算繪的是這個元件。沒掛時佇列在漲、畫面什麼都不顯示。
⚠️ 與 SwModalHost 不同：漏掛時沒有任何執行期提示 —— SwModalHost 會 console.warn 提醒，SwToast 目前無此兜底（已核原始碼），連 warning 都沒有。排查「toast 不彈」第一步就是確認 app.vue 裡掛了 <SwToast />。
回饋管道按場景選，別拿 toast 當萬能（Rule UX-008）—— 成功 / 輕量提示用 toast；需要使用者決策的用 useModal()；欄位級驗證錯誤就近 inline 顯示（SwFormField），塞進一閃而過的 toast 使用者根本來不及看。
自帶預設皮膚 + 四類語意配色（不是零樣式）—— framework 預設注入 toast.css：頂部置中浮層、半透明卡片（底色 / 邊框 / 陰影），並按 data-type 給出 ✓ / ✕ / ! / i 圖示與配色（--sw-toast-icon-success/error/warning/info 預設對映 --success / --destructive / --warning / --info）。改色覆寫對應 --sw-toast-* 變數即可；元件同時輸出 [data-type="..."] 語意屬性，需要完全自訂視覺時用它做選擇器。整套關掉：swift.config.json 的 framework.styles.toast = false。