零依赖弹通知神器Ding:真实弹簧物理Toast的完整指南

原创2026-11-14 10:15:051,812 阅读

零依赖弹通知神器Ding:真实弹簧物理Toast的完整指南

如果你正在为 React、Svelte、Vue 或原生 DOM 项目挑选 Toast 通知组件,不妨看看 Ding——一款零依赖、带真实弹簧物理动画的弹通知库。它最特别的地方在于:同一时刻只有一个 Toast,新的通知会在屏幕上**原地变形(morph)**成新的内容,而不是堆叠出第二个弹框;动画由真正的弹簧解算器驱动,中途打断也能保留惯性,视觉上自然流畅。

Ding 零依赖 Toast 通知组件:真实弹簧物理动画演示

为什么选择 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 通知方案。

登录后查看全文
ding