Toast 使用手册

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

组件介绍

用短暂通知反馈操作结果或状态变化，支持图标、操作和富内容，适合保存成功、错误与提醒。

使用选择

用于短暂的操作结果反馈，配合 Toaster 管理展示。通知历史、活动记录使用常驻内容列表，不使用 Toast。

• 调用 toast 发送短暂反馈，由 Toaster 管理队列；独立渲染时页面负责关闭后的移除。

• as="toast" 可接入宿主点击触发；leading / trailing 组合附属内容，parts 只配置默认关闭按钮。短标签使用继承的 singleLine 与 Text lines={1}；内部有效间距至少4 CSS px，rich 多行正文保持原布局。

快速开始

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

<script lang="ts">	import { Toast, Button, Text } from '@snowui-design-system/components';</script> <div style="display: flex; flex-direction: column; align-items: center; gap: var(--gap-4); max-width: 100%;">	<Toast singleLine><Text lines={1}>Draft saved</Text></Toast>	<Toast positive singleLine><Text lines={1}>Changes published</Text></Toast>	<Toast positive={false} singleLine><Text lines={1}>Connection lost</Text></Toast></div>

API

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

使用边界与详细说明

Toaster 内置组件双模式

• Toaster.parts.Toast：统一配置 Toaster 直接生成的 Toast；Toaster.parts.Text 只配置 text 字符串生成的标签，不接管自定义 children。

• Toast 队列状态、position 与关闭事件由 Toaster 控制；外置显式 Props 高于 part。

Toast 是 SnowUI 的全局通知组件。整套能力由三件交付物组成：

独立 Panel 模式的 Toast 根显式使用 GENERIC_SCALE_APPEAR_MOTION，保持原 Frame generic appear 的 opacity + scale 视觉与标准时序，不再通过 whileAppear={true} 隐式跟随 Frame fallback。Toaster 队列仍使用位置相关的显式 slide + opacity + scale 组合，两层既有视觉均保持不变。

功能概览

• 6 个固定位置：top / top-left / top-right / bottom / bottom-left / bottom-right，距视口边缘 16px，默认 top

• 三槽位布局（Leading / Content / Trailing）；内置图标支持外置 Icon 替换

• 默认变体（default）：深色 pill，并使用 blur(var(--size-10)) 背景模糊；rich 变体：Background/3 玻璃卡片，复用 .snowui-quick-action-panel 的背景模糊

• 自动消失：默认 4 秒；duration: 0 表示常驻

• 自动消失计时在最上层 Toast hover 时暂停，离开 hover 后按剩余时间恢复

• 多个同位置 Toast 自动堆叠（HeroUI 风格）：默认 gap=8、maxVisible=3、scaleStep=0.05、stackOpacityStep=0.2、宽度内容自适应（均可配置）

• 出现、退出、堆叠前移与最后一层被挤出动效均在 Toast 根元素组合：生命周期使用 transform + opacity，堆叠使用独立 translate + scale，堆叠透明度直接合并进 Frame fade 数值；关闭时先进入 Disappear，动画完成后再从队列移除

布局模型

主布局模型：复合管理布局。

• Toaster 是页面级 Portal，挂载到 <body> 上，使用 6 个绝对定位区域承载 Toast 栈；每个栈槽位是绝对定位的 Frame，由 currentState="Appear" | "Disappear" 驱动默认动效

• 栈槽位按 HeroUI 的 index 规则写入 translate / z-index：frontmost index = 0，后层向内侧偏移

• 非 frontmost Toast 禁止交互，但仍保留真实 Toast 内容；叠层差异由位移、缩放、透明度三种动效组合给出

• 单条 Toast 内部为槽位宿主布局（Frame row + 三槽位），Leading / Content / Trailing 标准结构

• 关闭 X 按钮属于 rich 变体的内置 trailing 装饰；通过绝对定位浮在 Toast 右上角，不参与三槽位

toast(input) — 命令式入口

import { toast } from "@snowui-design-system/components"; toast("Done");                                        // 字符串语法 → 等价 { text: "Done" }toast({ text: "Done", positive: true });              // 积极语义 → 绿色 CheckCircletoast({ text: "Something Wrong", positive: false });  // 问题语义 → 黄色 Warningtoast({ text: "Plain Notice" });                      // 不传 positive → 不显示内置图标const id = toast({ text: "持久通知", duration: 0 });dismissToast(id);                                     // 手动关闭showToast("saved-template");                          // 触发 <Toast template id="saved-template">

辅助函数：

• dismissToast(id: string): void — 关闭指定 Toast

• dismissAllToasts(position?: ToastPosition): void — 关闭全部或指定位置的 Toast

• showToast(id: string, overrides?: ToastOptions): string | undefined — 通过 <Toast template id="..."> 注册的模板触发通知；overrides 可覆盖位置、时长等运行时参数

<Toaster />

动效要点

结论：

• Toast 动效采用单根元素组合结构。whileAppear / whileDisappear 输出生命周期 transform 与 --su-motion-opacity；堆叠位移和缩放分别使用 CSS 独立属性 translate / scale，不会覆盖生命周期 transform。

• 堆叠透明度直接乘入生命周期 fade 数值；默认第 2 层为 0.8、第 3 层为 0.6，退场时再降低当前透明度的 20%。

• 退出额外越界距离直接合并进 --snowui-toast-stack-translate-y，与生命周期的百分比位移共同作用，确保深层 Toast 也能越过可视区域边缘。

• 背景、阴影和 backdrop-filter 始终属于同一个 Toast 根元素，不创建独立 blur plate。

• maxVisible 只限制可见层数，不限制 toast() 入队数量。超过可见层后，当前最后一层进入 pushed-out，不是丢弃新 Toast。

• 自动消失计时在同位置任一可见层 hover 时暂停，离开后恢复；只有 idle 层 hover 显示关闭 X，后层不显示 X。

动效参数表

<Toast />（视觉单元）

继承 FrameProps（排除 children），并新增：

v2.0.0 起：移除 title / description / icon 三个 prop。文字内容统一通过 children 外置；内置图标由 positive 判定(undefined 时不显示)。

全局挂载 + 命令式触发

<script>    import { Button, Frame, Text, Toast, Toaster, showToast, toast } from "@snowui-design-system/components";</script> <Toaster /> <Button onclick={() => toast("Done")}>Show Toast</Button><Button onclick={() => toast({ text: "Something Wrong", positive: false })}>    Warning</Button><Button    onclick={() =>        toast({            text: "Saved",            positive: true,            variant: "rich",            position: "top-right",        })    }>    Rich Toast</Button>

静态使用（不通过 toast()）

<Toast positive>Done</Toast><Toast positive={false}>Something Wrong</Toast><Toast>Plain Notice</Toast><Toast variant="rich" positive>    <Frame column class="flex-1 min-w-0">        <Text>Saved</Text>        <Text class="text-12 text-black-40">Your changes are synced.</Text>    </Frame></Toast>

内嵌模式 (v1.1.0,as="toast")

Toast 作为宿主子节点,点击宿主即触发,无需 id、无需手动 showToast。遵循 ComponentGuidelines.md §5 浮层组件三激活模式规范（源码参考：specs/maintainers/ComponentGuidelines.md）。

<Toaster /> <Button variant="filled">    保存    <Toast as="toast" positive position="top-right">已保存</Toast></Button>

声明式模板 + 按钮触发

<Toaster /> <Toast id="saved-rich-toast" template class="items-start" variant="rich" positive style="width: 15rem;">    <Frame column class="flex-1 min-w-0">        <Text>Text</Text>        <Text class="text-12 text-black-40">Text 2</Text>    </Frame>    <Button as="trailing" variant="gray">Button</Button></Toast> <Button onclick={() => showToast("saved-rich-toast", { position: "top-right" })}>    Add Rich Toast</Button>

替换内置图标

<Toast positive>    <Icon as="leading"><Heart /></Icon>    收藏成功</Toast>

此区域由用户维护；AI 修改前请先取得许可。