SwToast

SwToast 是全局通知组件，需要在 app.vue 或布局文件的根层放置一次，由 useToast() composable 命令式触发，无需每个页面重复引入。

安装与配置

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

SwToast 组件无需任何 props，它会自动监听 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。