零依赖弹通知神器Ding:真实弹簧物理Toast的完整指南
零依赖弹通知神器Ding:真实弹簧物理Toast的完整指南
如果你正在为 React、Svelte、Vue 或原生 DOM 项目挑选 Toast 通知组件,不妨看看 Ding——一款零依赖、带真实弹簧物理动画的弹通知库。它最特别的地方在于:同一时刻只有一个 Toast,新的通知会在屏幕上**原地变形(morph)**成新的内容,而不是堆叠出第二个弹框;动画由真正的弹簧解算器驱动,中途打断也能保留惯性,视觉上自然流畅。
为什么选择 Ding
| 特性 | 说明 |
|---|---|
| 🍃 零依赖 | 框架包只依赖很小的核心包,无第三方运行时依赖 |
| 🌀 真实弹簧 | 尺寸、形状、文字都跑在弹簧解算器上,打断动画也能保持动量 |
| 🔁 单个 Toast | 新调用让当前通知原地变形,不堆叠 |
| 🎨 无样式表 | 样式由 JS 注入,无需 import 任何 CSS |
| 🌗 主题与定位 | light/dark/system 三主题,6 个位置,支持 RTL 右到左 |
| ♿ 可访问性 | 常驻 live region、键盘关闭、尊重 prefers-reduced-motion |
| 🔊 可选提示音 | 每种状态一个轻柔提示音,也可插自己的 |
核心实现位于 packages/core/src/spring.ts,弹簧曲线会被"烘焙"成 CSS linear() 缓动,交给浏览器渲染,JS 不逐帧驱动,性能开销极低。
一键安装步骤
按需选择框架版本,只需一条命令:
npm i @yusufceng1z/ding-react # React 18+
npm i @yusufceng1z/ding-svelte # Svelte 5
npm i @yusufceng1z/ding-vue # Vue 3 和 Nuxt
npm i @yusufceng1z/ding # 原生 DOM
使用 shadcn/ui?一条命令即可安装 React 包并加入 ding-toaster.tsx 封装:
npx shadcn@latest add @ding/ding
最快上手:3 行代码弹出通知
思路统一:挂载一次 Toaster,之后随处调用 toast。
React(自带 "use client",可直接放进 Next.js App Router 的 app/layout.tsx)
import { Toaster, toast } from '@yusufceng1z/ding-react';
export default function App() {
return (
<>
<Toaster position="top-center" theme="system" />
<button onClick={() => toast.success('Saved')}>Save</button>
</>
);
}
Vue 3
<script setup>
import { Toaster, toast } from '@yusufceng1z/ding-vue';
</script>
<template>
<Toaster position="top-center" theme="system" />
<button @click="toast.success('Saved')">Save</button>
</template>
原生 DOM
import { mountToaster, toast } from '@yusufceng1z/ding';
mountToaster({ position: 'top-center' });
toast.success('Saved');
五种状态一目了然:
toast.success('Saved');
toast.error('Payment failed', { description: 'Card declined' });
toast.warning('Storage almost full');
toast.info('New version available');
toast.loading('Uploading…');
💡
Toaster在原地不渲染任何内容,挂载发生在onMounted,所以服务端渲染(SSR)是安全的。
Promise 跟踪与进度条
上传、保存等异步操作是 Toast 的主战场。toast.promise 一次搞定 loading → success/error 的状态流转:
toast.promise(save(), {
loading: 'Saving…',
success: 'Saved',
error: (err) => `Could not save: ${err.message}`,
});
手动更新进度也只需几行,而且只有最新调用者能更新共享 Toast,慢请求迟到时不会覆盖新消息:
const id = toast.loading('Uploading photo…', { progress: 0 });
toast.update(id, { progress: 0.6 });
toast.update(id, { type: 'success', title: 'Photo uploaded', progress: null });
撤销按钮:原地变形而不是关闭
action 的 onClick 可以返回一个补丁对象,Toast 就会原地变形成新内容,而不是消失:
toast.success('Message deleted', {
action: {
label: 'Undo',
onClick: () => {
restore();
return { type: 'info', title: 'Restored' };
},
},
});
这种"删除 → 撤销 → 恢复"的连续叙事,配合弹簧动画会非常丝滑。文档站里的实时示例逻辑就在 apps/docs/src/page-demo.ts。
常用选项速查
| 选项 | 作用 |
|---|---|
description |
第二行文字 |
action / secondary |
主按钮 / 次要按钮 |
image |
头像或缩略图,替换状态图标 |
meta |
末尾小字,如 now、⌘V |
progress |
0–1,在底部画一条细进度条 |
duration |
自动关闭毫秒数,0 为常驻,默认 5000 |
细节上也很贴心:错误、loading 和带按钮的 Toast 会常驻;鼠标悬停或键盘聚焦时暂停计时;重复弹出相同通知会折叠为 ×2 计数器。全部类型定义见 packages/core/src/types.ts。
全局配置与自定义样式
toast.configure({
position: 'bottom-right', // 六种位置任选
theme: 'dark', // system / light / dark
sound: true,
volume: 0.5,
});
颜色与圆角全部走 CSS 变量,改一处即全局生效,且跨框架通用:
.tst-viewport {
--tst-radius: 8px;
--tst-bg: #1e3a8a;
--tst-fg: #fff;
--tst-success: #16a34a;
}
默认值通过 light-dark() 自动跟随系统亮/暗主题。
提示音默认关闭,开启后每种状态音调不同:success 上扬、error 下坠、warning 双响。想用自己的音效,传一个函数即可:toast.configure({ sound: (type) => mySounds.play(type) })。
可访问性表现
- 消息经常驻 live region 播报:错误用 assertive,其余 polite
Esc关闭,Alt + T把焦点移入 Toast- 尊重
prefers-reduced-motion,动效敏感用户不受打扰 - RTL 页面自动镜像
默认无障碍名称是英文,可通过 labels 传入本地化文案(如中文"通知""关闭通知"),缺省项保留默认。
项目结构与源码导读
仓库是 monorepo,核心行为全部收敛在 core 包里,框架包只负责渲染:
| 包 | 说明 |
|---|---|
packages/core |
弹簧、计时器、store、提示音与原生 DOM 渲染器 |
packages/react |
React 渲染器 |
packages/svelte |
Svelte 5 渲染器 |
packages/vue |
Vue 3 渲染器 |
核心包内部模块划分清晰:spring.ts(弹簧解算)、store.ts(状态)、sound.ts(提示音)、styles.ts(样式注入)、vanilla.ts(原生 DOM 挂载)。想深入理解"弹簧是怎么变成 CSS 缓动"的,从 spring.ts 读起即可。
本地开发只需:
git clone https://gitcode.com/gh_mirrors/ding6/ding
cd ding
pnpm install
pnpm dev # 启动文档与演示站
pnpm test # 单元测试
总结
Ding 用零依赖 + 真实弹簧物理 + 单 Toast 原地变形,把最常见的弹通知场景做到了极简又高级:一条命令安装、三行代码上手、CSS 变量轻松换肤,还自带完善的可访问性。无论是 React、Svelte、Vue 还是没有框架的原生页面,它是值得放进工具箱的 Toast 通知方案。
