番茄时钟小程序源码解析：从倒计时逻辑到分包改造的完整实践

简介这是一份面向学生、自由职业者与程序员等需要高效管理时间人群的番茄工作法小程序源码帮助用户将工作拆分为25分钟专注块与5分钟休息循环从而提升专注力与时间利用率。压缩包共42个文件约1.29MB以js逻辑脚本、wxss样式表、wxml页面结构、json配置为主另含png与gif图标动效、url快捷方式及md说明文档构成完整的小程序工程目录。已有51人学习下载。资源围绕计时器、休息提醒、任务管理、统计分析、多模式与专注模式等核心功能展开读者可据此理解番茄钟的倒计时逻辑、任务番茄数统计与图表展示思路并参考个性化设置与云同步的工程组织方式快速搭建或二次开发属于自己的时间管理工具。1. 番茄时钟.zip 里到底装了什么一个能直接跑的小程序时间管理工具如果你正在找一份能直接导入、不用从零搭框架的番茄钟小程序源码番茄时钟.zip大概率就是你要的东西。它不是一个在线服务也不是某个 App 的安装包而是一份完整的小程序工程压缩包解压后能看到标准的app.json、pages目录、utils工具函数和若干页面组件。核心功能围绕番茄工作法展开25 分钟专注倒计时、5 分钟短休息、4 轮后进入 15 分钟长休息同时记录每日完成的番茄数和累计专注时长。适合两类人一是想快速拥有一个可运行的时间管理小程序的开发者二是需要拿现成工程改造成自己业务模块的从业者。它解决的是“从零写一个计时器 状态管理 本地存储”的重复劳动问题把最枯燥的倒计时逻辑、页面跳转和后台保活都替你写好了。你拿到手后改改配色、调调时长、接上自己的用户体系就能用。2. 拆包看结构页面路由、计时器与本地存储怎么串起来2.1 工程目录与核心文件职责解压番茄时钟.zip后根目录下是典型的小程序项目结构。我一般会先看app.json里的pages数组它决定了启动页和页面栈顺序。这个工程通常包含三个主页面index番茄钟主界面、records历史记录、settings时长与提醒设置。utils目录下一般会有一个timer.js或format.js负责把秒数转成mm:ss以及处理倒计时循环。app.js里做全局状态初始化比如从wx.getStorageSync读取用户上次设置的专注时长。app.wxss放公共样式页面级的.wxss只写差异部分。这种拆分方式的好处是你改设置页的开关不会影响到主界面的倒计时渲染。提示不同版本的压缩包目录名可能略有差异但app.json、app.js、app.wxss这三个文件一定在根目录认准它们就不会找错入口。2.2 倒计时逻辑setInterval 还是 setTimeout 递归番茄钟最核心的就是计时。这个工程里常见做法是用setInterval每秒更新一次剩余秒数但直接裸用setInterval会有两个坑一是页面隐藏后小程序会暂停定时器导致倒计时不准二是多次点击开始按钮会叠加多个定时器。所以合格的源码会在data里存一个timerId每次启动前先clearInterval再重新赋值。下面是我从这类工程里提炼出的典型实现你可以对照自己解压后的index.js看是否一致// pages/index/index.js Page({ data: { remainSeconds: 25 * 60, // 默认25分钟 timerId: null, isRunning: false }, startTimer() { if (this.data.isRunning) return; // 防止重复启动 this.setData({ isRunning: true }); // 先清掉可能存在的旧定时器避免叠加 if (this.data.timerId) { clearInterval(this.data.timerId); } const id setInterval(() { let remain this.data.remainSeconds - 1; if (remain 0) { clearInterval(id); this.setData({ remainSeconds: 0, timerId: null, isRunning: false }); this.onSessionComplete(); // 触发完成回调 return; } this.setData({ remainSeconds: remain }); }, 1000); this.setData({ timerId: id }); }, pauseTimer() { if (this.data.timerId) { clearInterval(this.data.timerId); this.setData({ timerId: null, isRunning: false }); } } });逻辑说明startTimer先判断isRunning防止连点然后清理旧timerId保证全局只有一个定时器在跑。每秒把remainSeconds减一减到 0 时清除定时器并调用onSessionComplete。参数说明remainSeconds是剩余秒数单位秒timerId存setInterval返回的 ID用于暂停和清理。你如果看到源码里没有clearInterval这一步那大概率是个半成品需要自己补上。2.3 本地存储用 wx.setStorageSync 记录每日番茄数番茄钟的成就感很大一部分来自历史记录。这个工程一般会在onSessionComplete里往本地写一条记录键名可能是tomato_records值是一个数组每项包含date、duration、type专注/休息。读取时用wx.getStorageSync(tomato_records) || []兜底避免首次打开报错。写入前先取当天日期判断数组里是否已有当天条目有就累加count没有就 push 新对象。这种设计不需要后端纯本地就能跑适合个人使用。但要注意小程序本地存储上限是 10MB如果记录只存日期和计数几年也撑不满如果每条都存完整时间戳和备注就要考虑定期清理。// 在 onSessionComplete 中调用 const today new Date().toISOString().slice(0, 10); // 取 YYYY-MM-DD let records wx.getStorageSync(tomato_records) || []; const idx records.findIndex(item item.date today); if (idx -1) { records[idx].count 1; } else { records.push({ date: today, count: 1 }); } wx.setStorageSync(tomato_records, records);参数说明today用 ISO 格式截取前 10 位保证跨时区时日期一致records是数组每项至少包含date和count。如果你要加累计专注分钟数就在每项里再加一个totalMinutes字段写入时同步累加。3. 跑起来改起来导入、调参与真机预览的完整操作链3.1 导入工程与基础配置检查拿到番茄时钟.zip后第一步是解压到一个不带中文和空格的路径下比如D:\projects\tomato-clock。然后打开微信开发者工具选择“导入项目”目录指向解压后的根目录。AppID 那里如果你没有自己的可以选“测试号”但测试号无法真机预览只能模拟器跑。导入后工具会自动读取project.config.json如果这个文件里的appid是占位符你需要手动改成自己的。接着看app.json里的pages第一项是不是pages/index/index这决定了启动页。如果启动后白屏优先检查app.json的pages路径和实际文件是否大小写一致——小程序对路径大小写敏感Index和index是两个东西。注意导入时如果提示“未找到 project.config.json”说明压缩包可能被解压工具多套了一层文件夹进去一层再导入即可。3.2 修改默认时长与轮次参数番茄工作法的标准是 25 分钟专注、5 分钟短休息、4 轮后 15 分钟长休息。但不同人习惯不同这个工程通常会把这几个值放在settings页面的data里或者抽到utils/config.js统一管理。我一般会先找到定义默认值的地方把25 * 60改成自己想要的秒数。比如你想改成 45 分钟专注就写45 * 60。轮次参数一般叫roundCount或cycleCount默认 4改成 3 就是三轮后长休息。改完后要同步检查onSessionComplete里的判断逻辑如果当前是专注且currentRound % cycleCount 0就进入长休息否则进入短休息。这个取模条件写错的话会出现“每轮都长休息”或者“永远不进入长休息”的玄学现象。// utils/config.js 常见写法 module.exports { focusDuration: 25 * 60, // 专注时长单位秒 shortBreak: 5 * 60, // 短休息单位秒 longBreak: 15 * 60, // 长休息单位秒 cycleCount: 4, // 每几轮进入长休息 autoStartNext: false // 是否自动开始下一段 };参数说明focusDuration等三个时长都按秒传因为setInterval按秒递减cycleCount是整数建议 2 到 6 之间autoStartNext控制一段结束后是否自动跳下一段设true适合不想手动点的人设false适合需要缓冲的人。3.3 真机预览与后台保活测试模拟器上跑通不代表真机没问题。点击开发者工具的“预览”用手机扫码打开。重点测两个场景一是锁屏或切到其他小程序后倒计时是否还在走二是从后台切回来剩余时间是否跳变。常见情况是小程序切后台后setInterval被系统暂停切回来时remainSeconds还是切走时的值但真实时间已经过了几分钟。解决办法是在onShow里记录一个backgroundTimestamp切回来时用Date.now()减去它算出实际过去秒数再从remainSeconds里扣掉。这个逻辑不复杂但很多现成工程漏掉了导致“锁屏五分钟回来发现倒计时没动”的翻车现场。// 在 Page 的 onHide 和 onShow 中处理 onHide() { this.setData({ backgroundAt: Date.now() }); }, onShow() { if (this.data.backgroundAt this.data.isRunning) { const elapsed Math.floor((Date.now() - this.data.backgroundAt) / 1000); let remain this.data.remainSeconds - elapsed; if (remain 0) { remain 0; this.onSessionComplete(); } this.setData({ remainSeconds: remain, backgroundAt: null }); } }逻辑说明onHide时记下时间戳onShow时算出后台停留秒数从剩余时间里扣。如果扣到 0 以下直接触发完成回调。参数说明backgroundAt只在运行中才记录暂停状态切后台不需要补偿。4. 避坑与排查番茄钟小程序最容易翻车的五个地方4.1 倒计时越走越慢或跳秒现象模拟器上每秒减一真机上偶尔一次减两秒或者明显比真实时间慢。原因setInterval本身不保证精确间隔加上setData渲染耗时累积误差会越来越大。解决不要依赖setInterval的调用次数来计时改成在每次回调里用Date.now()和开始时间戳做差算出真实剩余秒数再setData。这样即使某次回调延迟了下一次也会自动校正。4.2 点击开始后按钮没反应现象点了开始按钮界面没变化倒计时不动。原因isRunning状态没更新或者timerId被重复赋值导致旧定时器没清掉。解决在startTimer第一行加if (this.data.isRunning) return;并在设置timerId之前先clearInterval旧值。另外检查按钮的bindtap事件名是否和Page里定义的方法名完全一致大小写错一个字母就静默失败。4.3 历史记录日期对不上现象晚上 11 点完成的番茄记录到了第二天。原因new Date().toISOString()返回的是 UTC 时间东八区会比本地时间早 8 小时。解决不要用toISOString改用new Date().toLocaleDateString(zh-CN)或者手动拼getFullYear、getMonth、getDate。如果一定要用 ISO 格式就先减去时区偏移再截取。4.4 真机上长休息不触发现象完成了 4 个番茄但第 4 个结束后还是短休息。原因轮次计数器currentRound在每次专注结束后没有正确累加或者取模条件写成了currentRound % cycleCount 1。解决在专注完成回调里先currentRound 1再用currentRound % cycleCount 0判断是否长休息。注意初始值设为 0第一个番茄完成后变成 1第四个完成后变成 44 % 4 0触发长休息。4.5 本地存储写入失败现象wx.setStorageSync报错历史记录丢失。原因存储值超过了单个 key 的大小限制或者存了undefined。解决写入前用JSON.stringify序列化读取时用JSON.parse反序列化并加try/catch兜底。如果记录数组太长只保留最近 30 天超出的用splice删掉。另外注意wx.setStorageSync是同步接口频繁写入会阻塞渲染建议在完成番茄时写一次不要每秒都写。5. 进阶改造把番茄钟接进自己的小程序主包与分包策略5.1 作为分包页面嵌入现有工程如果你已经有一个主包想把番茄钟作为独立模块挂进去最省事的做法是把整个pages/tomato目录复制到你的工程里然后在app.json的subpackages中注册。分包的好处是主包体积不增加用户首次打开主功能不受影响。配置时注意root写分包根目录pages写相对路径。比如{ subpackages: [ { root: packageTomato, pages: [ pages/index/index, pages/records/records ] } ] }参数说明root是分包根目录名不能和主包或其他分包重名pages数组里的路径是相对于root的不要带root前缀。配置完后从主包跳转用wx.navigateTo({ url: /packageTomato/pages/index/index })。注意分包页面不能直接引用主包的私有组件公共组件要放到主包或独立分包里。5.2 用自定义 tabBar 把番茄钟做成常驻入口想让番茄钟在底部导航栏一直可见可以改用自定义 tabBar。在app.json里设tabBar: { custom: true, list: [...] }然后建一个custom-tab-bar组件目录。这个组件里用cover-view或普通view画按钮点击时用wx.switchTab跳转。番茄钟页面作为其中一个 tab 页切走再切回来时onShow会触发正好用来做后台时间补偿。但要注意自定义 tabBar 在页面切换时不会重新创建状态要存在全局或本地存储里否则切回来倒计时状态就丢了。5.3 验证改造是否成功的三个检查点改完之后别急着提交按这三步走一遍第一从主包入口跳转到番茄钟分包看能否正常打开且倒计时启动第二切到其他 tab 再切回来看剩余时间是否按真实时间扣减第三完成一个番茄后看历史记录页是否多了一条当天数据。这三步都过了基本就能上线体验版了。我自己的习惯是每次改完计时相关逻辑都强制在真机上锁屏五分钟再回来对一次时间这个动作帮我拦住了至少三次“看起来正常但实际会漂移”的提交。希望帮到你。本文还有配套的精品资源点击获取