Toaster 使用手册

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。公开 API 配置与内部实现修改分别按许可处理；全部组件使用统一运行包，源码权益以许可为准。

组件介绍

集中展示通过 toast() 触发的全局通知，支持六个屏幕位置、堆叠动效与可见数量控制，让连续反馈保持有序。

使用选择

作为 Toast 的展示宿主，协调通知队列与布局。普通页面通知列表由业务页面组织，不把历史消息全部转成瞬时 Toast。

• 挂载为通知展示宿主，使用 toast 创建消息；maxVisible 限制同时可见数量。

• 同一运行实例的命令式通知共用队列，在应用根部挂载一个 Toaster，让多个页面区域复用；重复挂载会重复展示同一条通知。

• offset / gap 控制位置与堆叠间隔；parts 配置默认 Toast 及字符串通知生成的 Text，单条消息的显式外观优先。

快速开始

以下示例展示推荐的基本组合。更多场景与组合限制见后文。

<script lang="ts">	import { Button } from '@snowui-design-system/components';	import { Toaster, toast, dismissAllToasts } from '@snowui-design-system/components';</script> <div style="display: flex; align-items: center; justify-content: center; flex-wrap: wrap; gap: var(--gap-4) var(--gap-3);">	<Button onclick={() => toast({ text: "Changes saved", positive: true })}>Save changes</Button>	<Button onclick={() => toast({ text: "Connection lost", positive: false })}>Connection error</Button></div><Toaster />

API

未重新声明的继承能力请查所属基础组件文档；本表只列本组件源码具名公开属性。

使用边界与详细说明

内置组件双模式

• parts.Toast：统一配置 Toaster 直接生成的全部 Toast；parts.Text 只配置 text 字符串生成的标签，默认单行并提供截断全文。

• Toast 队列数据、position、关闭事件和堆叠动效由 Toaster 控制，不能由 part 覆盖。

• parts 只作用于 Toaster 直接创建的 Toast 与 text 标签，不递归进入 Toast 内部，也不接管显式 leading / children / trailing。

• Toast 实例显式 Prop 高于 parts.Toast；class 合并，style 按 parts 在前、显式 style 在后合并。

示例

<Toaster    parts={{        Toast: {            variant: "rich",            size: "md",        },    }}/>

完整 Toast API 见 Toast.md。

定位规则

• top / bottom 的区域占据视口左右 offset 之间的可用空间，通知按自身宽度在区域内居中；通知宽度仍由内容或 width 决定。

• 区域不依赖绝对定位子项提供内禀宽度，避免空区域宽度为 0 时通知从视口中线向右展开。