YusufCeng1z/ding

项目介绍

Ding 是一个 Toast 通知库，同一时刻屏幕上只保留一个提示：新的调用会让当前 Toast 在原地变形，而不是叠出第二条消息。尺寸、形状和文字的动画由弹簧求解器驱动，动画被打断时仍保留动量。它发布三个共享核心的包：原生 DOM 的 @yusufceng1z/ding、面向 React 18+ 的 @yusufceng1z/ding-react 和面向 Svelte 5 的 @yusufceng1z/ding-svelte。核心包负责弹簧、计时器、状态存储、声音和 DOM 渲染，框架包只负责渲染 包结构。

它适合希望在通知组件中直接获得动效和无障碍支持、又不想引入样式表或其他依赖的开发者。内容支持描述文字、头像、操作按钮、进度条、倒计时线和尾部小字；主题有亮色、暗色和跟随系统，另有六个位置、从右到左布局和可选音效，均可通过同一套 API 配置 功能概览。

安装与快速开始

只需安装对应框架的包，它们都会依赖体积很小的核心包 安装说明：

npm i @yusufceng1z/ding-react    # React 18+
npm i @yusufceng1z/ding-svelte   # Svelte 5
npm i @yusufceng1z/ding          # plain DOM

渲染一次 Toaster，然后在任意位置调用 toast。React 示例 快速开始：

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>
    </>
  );
}

Svelte 5 与原生 DOM 的写法类似：前者放 <Toaster /> 再调用 toast.success(...)，后者先 mountToaster({ position: 'top-center' }) 再调用 toast Svelte 示例 原生 DOM 示例。使用 shadcn/ui 时，注册表命令 npx shadcn@latest add @ding/ding 会安装 React 包并生成 ding-toaster.tsx 包装组件 shadcn 安装。

状态快捷方法包括 toast.success、error、warning、info 和 loading，都会返回 Toast id。toast.promise 负责映射加载、成功和失败状态，toast.update(id, patch) 可以原地修改 Toast。操作按钮的回调可以返回一个 patch，让 Toast 变形而不是关闭，适合撤销这类流程 Promise 与更新 操作按钮。

配置与行为

toast.configure 设置位置、主题、声音和音量，toast.dismiss(id) 或 toast.dismiss() 关闭单条或全部 Toast 配置说明。默认 5 秒后关闭，传 0 则常驻；错误、加载中以及带按钮的 Toast 会一直保留，鼠标悬停和键盘聚焦会暂停计时，重复触发同一条 Toast 会显示 ×2 计数 选项表。

声音默认关闭。设置 sound: true 后每个状态有自己的内置音调，也可以传入一个接收状态的函数来播放自定义音效；浏览器在用户点击或按键之前会锁定音频 声音说明。无障碍支持包括常驻的 live region（错误用 assertive，其他用 polite）、Esc 关闭、Alt + T 将焦点移入 Toast、遵循 prefers-reduced-motion，以及在 RTL 页面自动镜像 无障碍。

样式由 JavaScript 注入，无需导入样式表。包同时提供 ESM 和 CommonJS 构建，代码使用严格 TypeScript。

使用约束

React 支持要求 React 18 及以上，Svelte 包面向 Svelte 5。由于新 Toast 会替换旧 Toast，它不适合需要同时显示多条消息的界面。音效依赖用户先与页面发生交互。仓库采用 MIT 许可证 许可证，开发流程为 pnpm install、pnpm test、pnpm typecheck 和 pnpm build 开发说明。在线演示与文档位于 ding.yusufcengiz.dev。

HotRepo 点评

Ding 在 2026-11-07 进入 HotRepo 新项目榜的 TypeScript 榜单，当时有 102 个 Star、2 个 Fork，统计窗口约一小时，记录新增 2 个 Star。这只是项目早期的一次快照，只能说明它上过榜，不足以判断增长趋势。从源码能确认的差异点是：以弹簧求解器驱动单条 Toast 原地变形，并把核心与框架包拆开。是否适合，应结合你自己的交互需求评估，而不是参考 Star 数。