介紹 new-js-clock

open-sourcejavascripttypescriptrelease

15 年多前，我發佈了一個名為 JS-Clock 的小型 jQuery 插件。那是一個簡單的小工具，能夠在 DOM 元素內呈現一個滴答作響的時鐘——實用、簡潔，完全是那個年代的產物。它依賴於 jQuery，在多實例支援方面存在一些問題，自首次發佈後也從未作過任何有意義的更新。

今天，這一切改變了。我正式發佈 new-js-clock 1.0.0——一個從零開始以 TypeScript 重寫的版本，在保留原版精神的同時，將每一項局限都拋在了身後。你可以在示範頁面上親眼看到它的實際效果。

1.0.0 的新功能

此次版本帶來的所有更新：

  • 🔒 TypeScript — 整個代碼庫均具備完整的類型安全，配備全面的介面定義。
  • 🌐 E2E + 單元測試套件 — 確定性的 Jest 覆蓋率，加上在真實瀏覽器中執行的 Selenium E2E 測試，包含背景分頁行為的延伸驗證。
  • 📦 零依賴 — 純粹的 vanilla JavaScript，無需 jQuery。
  • 🐛 錯誤修復 — 多實例支援現已正常運作，這是 0.8 版本的主要問題。
  • ⚡ 現代 API — 乾淨直觀的 API，每個建立的時鐘都擁有完整的實例方法。
  • 🧪 完整測試 — 162 個確定性 Jest 測試，行覆蓋率 99.74%、語句覆蓋率 99.02%、函式覆蓋率 100%、分支覆蓋率 98.32%。
  • 🐳 Dockerized E2E 網格 — Selenium Grid 可在本地及 CI 環境中透過 pnpm run e2e:docker 執行無頭 Chrome、Firefox 及 Edge。
  • 📱 ES 模組 — 支援 tree-shaking 的 ES Module 匯入，同時提供 CommonJS 及 IIFE 打包版本。
  • 🌍 支援夏令時的時區 — 採用 IANA 時區，自動處理夏令時切換。
  • ⏱️ 碼錶模式 — 全新碼錶功能，從 00:00:00 開始向上計時。
  • 🏁 圈數及分段時間 — 在碼錶模式下記錄圈數時間（delta）及累計時間（split）。
  • 📊 最佳／最差圈數 — 內建輔助函式，輕鬆找出單次計時中最快及最慢的圈數。
  • 🎯 高精度計時 — 透過 performance.now() 量度圈數差值，精度達毫秒以下。

安裝方式

npm install new-js-clock
# 或者
pnpm add new-js-clock

也可透過 CDN 直接在瀏覽器中使用——請參閱 README 以取得 unpkg 及 jsDelivr 的連結。

為何花了這麼長時間？

說實話？是人生。原版 JS-Clock 是應我已故好友 Gustavo Beltrão（那個年代的 PHP 高手，我有幸與他合作過不止一次）的請求而寫的，用於企業內部儀表板以及面向來自不同時區訪客的單頁活動網站。它的表現足夠稱職，讓我從未覺得有迫切需要重新審視它。但 jQuery 早已在現代項目中銷聲匿跡，TypeScript 成為了函式庫開發的標準，而多實例支援的錯誤也一直讓我耿耿於懷。當我終於下定決心好好修復它時，就覺得應該做得徹底——加入類型、測試、現代模組系統，以及足夠的功能讓它在 2026 年真正派上用場。我也打算在下一個商業項目中使用它。

遲到好過無到。

願榮耀單單歸於耶穌基督！