PomoBox 制作记:为什么计时只存 endAt、长休息怎么判断、提示音与系统通知如何分层,以及刷新、关页、改设置时哪些东西会丢。
番茄工作法的规则很简单:专注 25 分钟,休息 5 分钟,四个循环之后长休息。难的从来不是规则,而是那些不显眼的细节——切到别的标签页之后,计时还准吗?电脑合盖再打开呢?专注结束时你正在看文档,怎么让你知道?
PomoBox 是给这些问题写的番茄钟。原生 HTML/CSS/JavaScript,无框架、无构建、零依赖,三个文件一共 660 行。任务、设置和统计全部放在 localStorage 里,在线版在 pomo.adcakeyuan.top。

截图来自本地实际运行(Playwright 驱动,固定时钟跑完 9 个番茄);界面里的数据是测试数据。
四个变量就够了
计时部分的状态只有四个:
let phase = 'focus' // focus | short | long
let running = false
let endAt = 0 // 运行中:唯一的真相
let remainMs = data.settings.focus * 60000另一个对象 data 是持久层,装 settings、tasks、stats 和 cycle。计时状态不落盘,页面刷新就回到一个新的专注阶段。
start() 只做一件事:把 remainMs 换成绝对时间点 endAt = Date.now() + remainMs,再把 running 置为 true。pause() 反过来,把 endAt - Date.now() 存回 remainMs。reset() 把 remainMs 设回当前阶段时长。completePhase() 负责记账和切换阶段。按钮、空格键和定时器都只调用这几个函数,没有第五条改状态的路径。
UI 也不保存第二份倒计时。render() 每次都从这四个变量里算:
const total = durationOf(phase)
const remain = running ? Math.max(0, endAt - Date.now()) : remainMs圆环偏移、按钮文字、阶段标签、标题和 favicon 全是派生值。少一个可写状态,就少一类「显示和实际对不上」的 bug。
没有引入状态库,不是反对状态库,而是这个页面只有四个变量、五个入口;真写一个 reducer,样板代码会比状态本身还长。
计时:时间戳,而不是每秒减一
页面里有一个 250ms 的 setInterval,但它只做两件事:调用 render(),以及检查是否已经越过 endAt。倒计时不是靠 tick 减出来的。
浏览器会节流后台标签页的定时器,系统休眠时干脆停掉。如果每次 tick 减 250ms,切走十分钟回来就会少走十分钟。时间戳没有这个问题:回到页面的第一帧,endAt - Date.now() 自动把该扣的时间扣掉。
实测时用假时钟把时间向前推 2 分钟、期间只触发一次 tick,界面从 25:00 直接变成 23:00。暂停 10 分钟再继续,时间仍是暂停时的 24:00;恢复后一分钟,23:00。
250ms 是为了圆环看起来平滑。标题和 favicon 则只在格式化后的 mm:ss 变化时重绘,避免每秒往 canvas 里画四次。页面从后台回来时,visibilitychange 会主动 render() 一次,不用等下一个 tick。
代价是没有保存计时状态。刷新页面,阶段回到专注、时间回到当前设置的完整时长——实测确实如此。这不是遗漏:提醒只存在于页面里,关掉页面后即使保存了 endAt,也没人给你发通知;下次打开补一条迟到的「专注完成」没有意义。要让计时跨页面存活,需要 Service Worker 和后台通知,那是另一个量级的工程。
长休息靠累计,不靠当天
completePhase() 只有两个分支:完成的如果是专注,记账,然后决定短休息还是长休息;如果完成的是休息,回到专注。
data.cycle++
const next = data.cycle % data.settings.longEvery === 0 ? 'long' : 'short'cycle 是累计值,不是当天值:今天做到第 3 个,明天完成的第一个是第 4 个,仍然会进长休息。提示文案也直接算 cycle % longEvery。默认每 4 个番茄一次长休息,这个数字可以在设置里改成 2 到 8。
统计按本地日期归档:todayKey() 拼出 YYYY-MM-DD,完成时 count + 1、minutes += settings.focus。分钟数记的是设定时长,不是秒表实测。暂停十分钟不会少记;专注中途把时长从 25 改成 10,则会按 10 记——这是选择,不是精度问题。
跳过按钮调用 completePhase({ record: false }):不增加 cycle、不写统计、不记任务番茄,但仍然播放完成音和系统通知。record 只控制记账,不控制提醒,这一点在测试里确认过。如果希望跳过完全安静,需要再拆一个参数。

提醒:三层,各自降级
第一层是标签页标题和 favicon。 render() 发现 mm:ss 变化时,把标题改成「23:30 · 专注中 — PomoBox」,同时在 64×64 的 canvas 上画一个阶段色的圆角方块和剩余分钟,转成 data URL 塞进动态 favicon。深色主题下文字颜色会翻转,避免图标在深色标签栏里糊掉。它不需要任何权限,只要标签页还在,扫一眼就能看到。
第二层是 WebAudio 合成提示音。 没有音频文件:专注结束是上行三音(C5-E5-G5,523.25 / 659.25 / 783.99 Hz,间隔 0.18 秒),休息结束是下行两音(659.25 → 523.25)。每个音是正弦波,增益从 0.0001 指数升到 0.2,再落回 0.0001,持续约 0.55 秒。
const notes =
kind === 'focus'
? [
[523.25, 0],
[659.25, 0.18],
[783.99, 0.36],
]
: [
[659.25, 0],
[523.25, 0.22],
]没有声音文件,就没有加载失败。AudioContext 被浏览器挂起时,start() 里会再 resume 一次;整个函数包在 try/catch 里,静音设备不会让计时中断。本地测试捕获到的振荡器频率与这三个值一致。
第三层是系统通知,默认关闭。 打开开关时才请求权限,之后每次完成都检查 permission === 'granted'。文案分两种:专注结束是「专注完成!🍅 / 休息一下,再战一轮」,休息结束是「休息结束 / 准备好开始新的专注了吗?」
它的边界最多:用户可能拒绝权限,系统可能开着专注模式,浏览器可能不支持;而且没有 Service Worker,页面关掉就不会有通知。本地测试在授权后捕获到 9 次专注加 9 次休息共 18 条通知调用,但那只证明调用路径通,不证明每个平台都能弹出。
三层不是冗余,是降级:favicon 永远可用,声音不需要权限,通知最强也最不可靠。任何一层失效,另外两层仍然把信息送到。
数据只存本机,也接受本机的边界
存储是一个版本化的 key:pomobox-v1。结构只有五项:settings、tasks、activeTaskId、stats、cycle。
加载时先 try/catch 解析 JSON,再逐项校正:settings 和默认值合并;tasks 必须是数组,stats 必须是对象,cycle 必须是数字,activeTaskId 缺失就是 null。手动把 localStorage 改成非法 JSON 再刷新,页面仍然以默认设置正常启动,控制台没有报错——这是专门验证过的一条。
每次修改都立即 save(),没有草稿态,也没有退出确认。
任务清单只允许一个「当前任务」。完成的番茄只记给当前任务,且任务被勾选完成后不再累计:实测勾选后完成一个番茄,统计 +1,任务的 🍅 不变。删除任务会同时清掉它的番茄数;删除当前任务会清空选中。
统计只保留按天的聚合,不保留每次专注的起止时间;最近 7 天的柱状图按最大值缩放,今天用更深的颜色标出。
边界很清楚:没有账号、没有同步、没有导出。换设备或清除站点数据,历史就没了;页脚也直接写明「换设备不同步」。对隐私是优点,对换机是缺点,两者是同一件事。

设置里的两个边界
数字输入在 change 时校正:专注 1–120 分钟、短休息 1–30、长休息 1–60、几轮后长休息 2–8。输入 999 会变成 120,输入 0 会变成 1。
时长修改只在空闲时重置当前阶段的 remainMs;运行中改时长,endAt 不会重算。测试里把专注从 25 改成 10,时间仍是 23:00,但圆环按 10 分钟的总量计算,strokeDashoffset 变成负数(约 -947),圆环直接画满。要改时长,先暂停或重置。
主题是单独的 key:首次跟随系统,手动切换后记住选择;已经有页面打开时,系统主题变化不会实时跟随。空格开始/暂停,R 重置,输入框内不拦截。

为什么零依赖
这个应用只有三个文件、一个页面、四个状态。引入框架和构建之后,收益是组件化和类型检查,成本是构建链、依赖升级和更大的攻击面。PomoBox 选了前者不需要、后者也不想要的那条路:直接打开 index.html 就能用,部署就是推送静态文件。
代价也要认:状态和 DOM 的对应关系全靠手写,没有组件测试;提醒依赖页面存活;计时状态不持久化。对 660 行的个人工具,这些代价比依赖更轻。
番茄钟的价值不在功能多,而在那条循环是否可信:计时不被后台标签页带偏,结束提醒能从三种渠道里至少命中一种,数据留在自己手里。PomoBox 用四个变量、一个时间戳和三层降级把这件事做完,也把边界写在了明面上。
源码在 GitHub。
本文由 AI 自动写作流水线生成;文中的计时、阶段流转、暂停/刷新、通知与存储行为均在本机 Chromium 中实际运行验证,截图来自该环境。