@codejoo/counter

浏览器端的轻量高性能计数引擎。单个共享的 requestAnimationFrame 心跳驱动所有 count-up （数字滚动）与 count-down（倒计时），渲染方式可插拔——默认纯文本，也可用富 SVG/DOM 渲染插件 （翻牌、里程表、圆环）。

• count-up —— 数字从 from → to 动画，支持缓动、fps 节流、自定义格式/渲染、懒加载、分组、暂停/恢复。
• count-down —— 倒计时到截止点（ms / 单位 / Date / 日期串），支持格式化、懒加载、分组、生命周期钩子； 渲染/钩子共用的 ctx 除当前 value（复用元组 [d,h,m,s,ms]）外还有 ctx.oldValue——上一次值真正变化前的独立快照，方便对比哪些位刚发生了进位。
• 单心跳 —— 一个 rAF 循环跑所有任务，首个任务自动启动、空闲自动停止；热路径零分配。
• 渲染插件 —— 按需引入、可独立 import（tree-shaking 友好）、运行时不依赖核心：
  • card —— 翻牌 / 滑动 / 日历翻页 数字卡片。
  • odometer —— 滚轮里程表（minimal / full）。
  • ring —— 圆形七段倒计时：刻度环 + 双向装饰弧 + 逐秒排空进度环。

安装

pnpm add @codejoo/counter

快速上手

import { countup, countdown } from "@codejoo/counter";

countup(1234, "#total"); // 0 → 1234
countup(0, 99.9, { duration: 2000, fmt: (n) => n.toFixed(1) });
countdown(60_000, "#timer", { fmt: "mm:ss" });
countdown("2026-12-31 23:59:59", "#newyear", { fmt: "DD HH:mm:ss" });

渲染插件（独立入口，按需引入）

import { countdown } from "@codejoo/counter/count-down";
import { createRingRender } from "@codejoo/counter/ring";
import "@codejoo/counter/ring.css";
countdown(300_000, "#ring", { fmt: "mm:ss", render: createRingRender() });

各插件选项与 API：card · odometer · ring。

入口

| import | 内容 | | ------------------------------------------------- | ------------------------------------------- | | @codejoo/counter | 全部（核心 + count-up + count-down + 插件） | | @codejoo/counter/count-down | countdown | | @codejoo/counter/count-up | countup | | @codejoo/counter/card .../odometer .../ring | 对应渲染插件 |

各渲染插件运行时独立（仅以 type 依赖 count-down），import /ring 只会打包 ring 本身。

开发

pnpm dev      # 监听构建
pnpm build    # 多入口 ESM 构建 + 拷贝 css
pnpm test     # vitest (jsdom)
pnpm check    # 格式化 + lint

全量 API 手动测试台：用 Vite dev server 打开根路径 /（index.html）。