SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场sileo-react-toasts

sileo-react-toasts

前端与建站

查看项目

更新于 10-16 02:14

技能介绍

用途

Sileo 是一个用于在 React 应用中展示 Toast 通知的组件（npm 包名为 sileo）。按资料描述，它是一个「tiny, opinionated, physics-based」的 Toast 系统，使用 gooey SVG 形变（通过 feGaussianBlur + feColorMatrix 滤镜链）与基于 motion/react（原 Framer Motion）的弹簧动画，实现从胶囊（collapsed）到卡片（expanded）状态的平滑过渡，默认零配置即可获得较为精致的视觉效果。

资料明确指出，Sileo 不是通用通知中心，而是为单行反馈消息（可选可展开描述）设计的高度打磨、视觉独特的 Toast 系统。

主要能力

  • 状态方法：sileo.success / error / warning / info / action / show，均返回 Toast 的 id 字符串；show 会根据 options.type 选择状态，默认 success。
  • Promise 流程：sileo.promise(promise, opts) 把 loading 状态串联到 success/error，并返回原始 promise。第一个参数可为 Promise<T> 或 () => Promise<T>（便于懒执行）；success、error 可为静态 options 或接收结果的回调；可选 action 字段会在存在时替换 success Toast 为 action 状态 Toast。
  • Action Toast：通过 button: { title, onClick } 在展开区域内提供可点击按钮。
  • 定位：六种位置 top-left、top-center、top-right（默认）、bottom-left、bottom-center、bottom-right；可在 <Toaster /> 上设默认值，也可在单条 Toast 上覆盖。
  • 主题与填充色：theme 支持 light / dark / system，会自动设置 fill；light 时 fill 为 #1a1a1a，dark 时 fill 为 #f2f2f2，system 跟随 prefers-color-scheme 并响应系统切换。若同时设置 theme 与单条 Toast 的 fill，则单条 fill 优先。fill 默认 #FFFFFF。
  • 样式覆盖：styles 支持 title、description、badge、button 四个子元素的 CSS class 覆盖，使用 Tailwind 时需加 ! 提升优先级。
  • 数据属性选择器：如 [data-sileo-toast]、[data-sileo-title]、[data-sileo-description]、[data-sileo-badge]、[data-sileo-button]、[data-sileo-viewport]、[data-sileo-svg] 等，并可用 data-state、data-expanded、data-exiting、data-position、data-theme 过滤。
  • 自定义图标：icon 可传任意 React 节点替换默认状态图标，或传 null 不渲染图标。默认图标为内联 Lucide 风格 SVG：success 对勾、error X、warning 圆圈加叹号、info 救生圈、loading 旋转圆圈（CSS 动画）、action 右箭头。
  • JSX 描述：description 接受 ReactNode，可在展开区域渲染富内容。
  • 圆角：roundness 默认 16，控制 SVG 形状圆角；值越大 gooey 模糊半径越大（blur = roundness * 0.5），渲染开销更高，推荐 16。
  • autopilot：默认自动展开（约 150ms）与自动折叠（约在消失前 4 秒）。可设为 false（仅悬停展开），或传 { expand, collapse } 自定义毫秒数。
  • 关闭与清除：sileo.dismiss(id) 关闭指定 Toast；sileo.clear(position?) 清除全部或指定位置的 Toast；内置纵向滑动手势关闭，阈值 30px。
  • 粘性 Toast：duration: null 时不会自动消失，需程序化关闭或滑动关闭。
  • TypeScript：导出 SileoButton、SileoOptions、SileoPosition、SileoState、SileoStyles 以及 SileoPromiseOptions<T> 等类型。

使用方式

安装：

npm install sileo

资料说明 Sileo 需要 react 与 motion 作为 peer dependencies。

基础设置：在应用根布局挂载一次 <Toaster />，然后从任意位置导入 sileo 触发 Toast：

import { sileo, Toaster } from "sileo";

export default function App() { return ( <> <Toaster position="top-right" /> <YourApp /> </> ); }

基础调用：

import { sileo } from "sileo";

sileo.success({ title: "Saved", description: "Your changes were stored." }); sileo.error({ title: "Failed", description: "Could not save." }); sileo.warning({ title: "Warning", description: "Disk space low." }); sileo.info({ title: "Tip", description: "Try the new feature." }); sileo.show({ title: "Done", type: "success" });

Action Toast：

sileo.action({ title: "New version available", description: "Reload to update", button: { title: "Reload", onClick: () => window.location.reload(), }, });

Promise Toast 示例（资料原文）：

type User = { name: string };

const result = await sileo.promise<User>(createUser(data), { loading: { title: "Creating account..." }, success: (user) => ({ title: Welcome, ${user.name}!, }), error: (err: any) => ({ title: "Signup failed", description: err?.message ?? "Unknown error", }), });

Toaster 属性包括 children、position、offset（数字、CSS 字符串或按边对象）、options（合并进每条 Toast 的默认项）、theme。全局默认示例：

<Toaster position="top-right" options={{ fill: "#171717", roundness: 16, styles: { title: "text-white!", description: "text-white/75!", badge: "bg-white/10!", button: "bg-white/10! hover:bg-white/15!", }, }} />

CSS 变量可在 :root 或任意父元素覆盖，包括状态色（oklch 格式）--sileo-state-success / loading / error / warning / info / action、--sileo-width（350px）、--sileo-height（40px）、--sileo-duration（600ms）。

适用场景

资料表明 Sileo 适用于 React 应用中的单行反馈消息，例如保存成功、保存失败、磁盘空间告警、功能提示、带操作按钮的版本更新提示，以及基于 Promise 的流程（如创建账号、上传文件、请求数据）的 loading 到结果反馈。因其自带 "use client"，在 Next.js App Router 中可直接使用，无需额外包装。

限制与注意事项

  • 仅支持 React；依赖 motion（motion/react）作为 peer dependency。
  • 不是通用通知中心，定位为单行反馈消息加可选展开描述。
  • 关于内部行为：全局 store 为模块级单例；当用户未提供 id 时，Toast 使用 "sileo-default" 作为 id，这意味着重复调用 sileo.success(...) 且不传 id 会替换上一条 Toast（同 id 更新行为），需要多条同时存在同状态 Toast 时应提供唯一 id。
  • 更高的 roundness 会增加 SVG 模糊半径，渲染开销更高，资料推荐值为 16。
  • 可访问性方面：viewport 使用 <section> 与 aria-live="polite"；Toast 根元素为 <button> 以支持键盘聚焦；每个 SVG 图标含 <title>；遵循 prefers-reduced-motion: reduce 时禁用全部动画与过渡。
  • 资料中「The SILEO_POSITIONS constant array is also exported for iteration」与代码注释「Not exported from index (internal)」存在表述不一致，具体导出情况以实际包为准。
  • 官方文档、API 参考、Styling、Playground、GitHub 链接：https://sileo.aaryan.design/docs 、https://sileo.aaryan.design/docs/api 、https://sileo.aaryan.design/docs/api/toaster 、https://sileo.aaryan.design/docs/styling 、https://sileo.aaryan.design/play 、https://github.com/hiaaryan/sileo 。

关于授权许可、收费与价格信息，资料未提供。