【免费下载链接】pomotroid:tomato: Simple and visually-pleasing Pomodoro timer项目地址https://gitcode.com/gh_mirrors/po/pomotroid点击查看免费下载Pomotroid 是一款基于 TauriRust Svelte的番茄钟应用。本篇技术指南围绕其Settings → Timer设置区的一次关键改造展开将原先只能按整分钟步进的时长滑块升级为支持MM:SS键盘输入的精确设置能力timer-duration-keyboard-entry并同步完成数据库存储从「分钟精度」到「秒精度」的无损迁移、滑块与输入框的双向同步、空闲态计时表盘即时刷新以及统计视图的分钟取整修正。读完本文你将掌握这套改造从需求到数据库迁移、前端交互与验证测试的完整实现脉络。本文核心设计文档位于仓库的 2026-03-03-timer-settings-keyboard-entry/proposal.md配套规格、设计文档与任务清单分别为同目录下的 specs/timer-duration-keyboard-entry/spec.md、specs/settings/spec.md、design.md 与 tasks.md。一、改造背景为什么滑块不够用改造前的Settings → Timer区域每个时长Focus / Short Break / Long Break旁边只显示一个静态时间徽章如25:00用户只能通过 1 分钟步进的 range slider 调整时长。这意味着无法设置25:30、5:45这类带秒的精确时长所有值都以整分钟为单位写入数据库底层虽然已经存在以秒为单位的字段却永远只能收到整分钟的值。这正是 proposal 中Why一节描述的核心痛点时长滑块只支持整分钟增量把用户的番茄节奏强行限制在 1 分钟步长上。键盘输入MM:SS格式让用户对节奏拥有完全控制权而不是被迫接受一分钟的步进。二、需求与能力变更全景proposal 的What Changes列出了本次改造的完整范围变更项说明可编辑徽章每个滑块标签Focus、Short Break、Long Break旁的时长徽章变为可编辑输入框接受MM:SS格式交互方式点击徽章进入编辑态按 Enter 或失焦blur即提交值合法范围1:0060 秒 90:005400 秒范围外数值在提交时被钳制clamp秒级精度接受任意MM:SS值如5:39不再局限于整分钟存储改造计时器时长设置改为以整秒存入数据库而非整分钟数据迁移新增数据库迁移把既有分钟值转换为秒值新增能力New Capabilitiestimer-duration-keyboard-entry在 Timer 设置区用内联可编辑的MM:SS输入框替代静态时间徽章具备校验、钳制、Enter/失焦提交行为。修改能力Modified Capabilitiessettings计时器时长的数据库键从分钟分辨率整数time_work_mins、time_short_break_mins、time_long_break_mins改为秒分辨率整数time_work_secs、time_short_break_secs、time_long_break_secs需要为存量用户提供迁移。影响面ImpactTimerSection.svelte新增可编辑徽章组件滑块oninput继续以秒保存settings/mod.rs数据库键名变更Settings结构体字段类型不变本就以秒为单位db/migrations.rs新迁移将既有time_work_mins等行转换为新键下的秒值ipc/index.ts数据库键常量更新types.ts无需类型变更字段本就命名为*_secs见 types.ts 第 21-23 行。三、存储层改造分钟键 → 秒键的数据库迁移3.1 迁移决策与备选方案design.md 的Decisions记录了三种被否决的备选方案保留*_mins键、存十进制分钟如5.65——键名含义混乱且有浮点解析风险新旧键并存、加载时回退——加载逻辑变得含糊出现两个事实来源同键名原地更新——time_work_mins里存339会极其费解。最终决策是新增 MIGRATION_2 读取既有*_mins行、乘以 60 后写入*_secs行再删除旧的*_mins行让数据库键名与Settings结构体字段名一一对应消除此前「字段是秒、存储是分」的阻抗失配。3.2 MIGRATION_2 的完整 SQLdesign.md 的 Migration Plan 给出了可直接落库的 SQL且该 SQL 已原样实现于 db/migrations.rsINSERT OR IGNORE INTO settings (key, value) SELECT time_work_secs, CAST(CAST(value AS INTEGER) * 60 AS TEXT) FROM settings WHERE key time_work_mins; INSERT OR IGNORE INTO settings (key, value) SELECT time_short_break_secs, CAST(CAST(value AS INTEGER) * 60 AS TEXT) FROM settings WHERE key time_short_break_mins; INSERT OR IGNORE INTO settings (key, value) SELECT time_long_break_secs, CAST(CAST(value AS INTEGER) * 60 AS TEXT) FROM settings WHERE key time_long_break_mins; DELETE FROM settings WHERE key IN (time_work_mins, time_short_break_mins, time_long_break_mins); INSERT INTO schema_version VALUES (2);要点解读INSERT OR IGNORE保证幂等性——即便旧键存在重复情况也不会覆盖已有数据CAST(value AS INTEGER) * 60把分钟值转为秒值再CAST(... AS TEXT)写回 TEXT 类型的 SQLite 值列DELETE FROM settings WHERE key IN (...)删除全部旧键最后写入schema_version 2记录迁移版本。在 migrations.rs 的 run() 中通过版本判断if version 2 { ... }触发该迁移且每个迁移都包裹在BEGIN; ... COMMIT;事务中部分失败时数据库保持不变。3.3 默认值以秒为单位播种settings/defaults.rs 中默认值从分钟键改为秒键(time_work_secs, 1500), // 25:00 (time_short_break_secs, 300), // 5:00 (time_long_break_secs, 900), // 15:003.4 加载逻辑去掉* 60此前 Rust 的load()函数在读取分钟值时要做* 60换算改造后 settings/mod.rs 的 load() 直接从*_secs键读取不再有任何换算// DB stores seconds directly (since MIGRATION_2). time_work_secs: parse_u32(map, time_work_secs, d.time_work_secs), time_short_break_secs: parse_u32(map, time_short_break_secs, d.time_short_break_secs), time_long_break_secs: parse_u32(map, time_long_break_secs, d.time_long_break_secs),Settings结构体中的time_work_secs、time_short_break_secs、time_long_break_secs三个字段本就是u32秒类型见 settings/mod.rs改造后字段语义与存储语义完全一致。缺失键或解析失败时回退到Settings::default()默认 25/5/15 分钟保证降级安全。3.5 迁移验收场景specs/settings/spec.md 定义了迁移的验收标准存量用户无损迁移升级前time_work_mins 30升级后time_work_secs应为1800且旧键被删除新装默认播种全新安装应包含time_work_secs 1500、time_short_break_secs 300、time_long_break_secs 900且不含任何*_mins键亚分钟值跨重启持久化设置 Focus 为 5:39339 秒并重启后数据库time_work_secs应为339重置恢复秒级默认触发 Reset All Settings 后表中应为time_work_secs 1500不含time_work_mins旧键彻底清除迁移后SELECT key FROM settings WHERE key LIKE %_mins应返回零行。这些场景均有 Rust 测试对应实现save_and_reload_sub_minute_timesettings/mod.rs验证 339 秒的存取migration_2_converts_mins_to_secs_and_removes_old_keyssettings/mod.rs手工构造 v1 数据库并断言 30→1800、7→420、20→1200 的转换与旧键清零reset_defaults_restores_all_settingssettings/mod.rs验证重置后回到 25×60。四、前端交互可编辑 MM:SS 徽章4.1 交互规格specs/timer-duration-keyboard-entry/spec.md 明确定义了可编辑徽章的行为展示设置窗口打开时每个计时器徽章以MM:SS显示存储时长1500 s →25:00339 s →5:39进入编辑态点击徽章输入框获得焦点且文本被全选便于直接覆盖输入Enter 提交输入5:39按 Enter保存为 339 秒并回显5:39裸整数输入25视为整分钟保存 1500 秒并回显25:00低于下限解析结果不足 60 秒如0:30钳制为 60 秒1:00高于上限解析结果超过 5400 秒如91:00钳制为 5400 秒90:00非法输入无法解析如abc、::时保持原值并回显旧值失焦提交编辑后未按 Enter 直接点击他处行为与按 Enter 完全一致解析、钳制、保存Tab 提交按 Tab 提交并移动焦点到下一个可聚焦元素。design.md 的Decisions 3进一步明确了提交时接受的两种格式MM:SS——规范形式如5:39、25:00、1:05裸整数M或MM——按整分钟解释如25→25:00。秒分量钳制到0–59分钟分量保证MM * 60 SS落在 60–5400 之间。任何不匹配上述模式或解析后越界的值都会吸附到最近的合法边界提交后输入框回显为格式化后的MM:SS。4.2 源码实现解析、格式化与提交TimerSection.svelte 完整实现了这套交互核心是三个函数与两套边界常量const MIN_SECS 60; // 1:00 const MAX_SECS 5400; // 90:00 /** Parse MM:SS or bare integer minutes. Returns total seconds, or null on failure. */ function parseMMSS(input: string): number | null { const trimmed input.trim(); const colonIdx trimmed.indexOf(:); if (colonIdx -1) { const mins parseInt(trimmed, 10); if (isNaN(mins) || trimmed ) return null; return mins * 60; } const mm parseInt(trimmed.slice(0, colonIdx), 10); const ss parseInt(trimmed.slice(colonIdx 1), 10); if (isNaN(mm) || isNaN(ss) || ss 0 || ss 59) return null; return mm * 60 ss; } /** Format total seconds as M:SS or MM:SS. */ function formatMMSS(totalSecs: number): string { const mins Math.floor(totalSecs / 60); const secs totalSecs % 60; return ${mins}:${String(secs).padStart(2, 0)}; } /** Commit an edited badge value: parse, clamp, save. Reverts on invalid input. */ async function commitBadge(raw, currentSecs, dbKey, el) { if (raw null) { el.value formatMMSS(currentSecs); return; } const parsed parseMMSS(raw); if (parsed null) { el.value formatMMSS(currentSecs); return; } const clamped Math.max(MIN_SECS, Math.min(MAX_SECS, parsed)); await handleChange(dbKey, clamped); el.value formatMMSS(clamped); }行为细节聚焦全选onfocus中把当前值写入编辑态并把select()全选文本Enter / Escapeonkeydown中 Enter 走commitBadge后blur()Escape 则放弃编辑、回显格式化旧值并失焦规格外的贴心兜底失焦提交onblur调用commitBadge钳制提交Math.max(MIN_SECS, Math.min(MAX_SECS, parsed))把结果约束在 1:00–90:00保存链路handleChange调用 ipc/index.ts 的 setSetting即invoke(settings_set, { key, value })Rust 侧 commands.rs 的 settings_set 完成写库、重载并广播事件。4.3 样式视觉上与静态徽章一致改造后的输入框被刻意设计得与旧静态徽章视觉一致等宽字体、var(--color-hover)背景、圆角 3px、width: 5ch、透明边框仅在聚焦时切换边框与背景色见 TimerSection.svelte 样式段并在编辑时保留光标。Rounds 行仍使用静态徽章.slider-value--static因为它不需要键盘输入。五、滑块与徽章的双向同步5.1 规格要求滑块 → 徽章拖动滑块仍按 1 分钟粒度工作移动滑块更新徽章显示并以整分钟×60 秒保存徽章 → 滑块编辑徽章后滑块拇指移动到最近整分钟。5.2 同步算法design.md 的Decisions 4给出两条规则Slider move → badge updates按最近整分钟显示向数据库保存「整分钟 × 60」秒Badge edit → slider updates滑块位置为Math.round(totalSeconds / 60)最近整分钟的可视位置数据库保存精确总秒数。由于滑块oninput与徽章提交各自独立触发不存在双向循环风险。spec 中的验收场景拖动 Focus 滑块到 30 → 徽章显示30:00保存 1800 秒输入5:39→ 滑块拇指移到位置 6最近整分钟保存 339 秒输入25:00→ 滑块停在位置 25保存 1500 秒。5.3 源码印证在 TimerSection.svelte 中滑块位置由存储秒数派生let workMins $derived(Math.round($settings.time_work_secs / 60)); let shortMins $derived(Math.round($settings.time_short_break_secs / 60)); let longMins $derived(Math.round($settings.time_long_break_secs / 60));滑块配置为min1 max90 step1其oninput直接以秒提交oninput{(e) handleChange(time_work_secs, (e.target as HTMLInputElement).valueAsNumber * 60)}徽章提交后settingsstore 更新$derived自动把滑块拇指摆到Math.round(secs / 60)的位置。两条链路最终都汇入同一个setSettingIPC 调用由 Rust 侧统一落库。六、空闲态表盘即时刷新timer:reset 事件6.1 需求背景当计时器处于空闲态未运行、无已耗进度时修改时长设置主窗口的计时表盘应立即显示新的总时长无需用户手动重置计时器。spec 定义了两条场景空闲时改时长从 25:00 改为 5:39主窗口表盘立即显示完整的 5:39 圆环无需在主窗口做任何操作运行中改时长当前倒计时不受影响地走完新时长从下一轮开始生效。6.2 实现机制这条链路横跨前后端前端setSetting→ Rustsettings_setcommands.rstimer.apply_settings(new_settings.clone())同步计时引擎无论计时器处于何种状态都app.emit(timer:reset, timer.get_snapshot())广播更新后的快照——代码注释明确说明即使正在运行timer:reset处理器只调用timerState.set()不会打断倒计时下一次timer:tick会在 1 秒内自动对齐total_secs。计时引擎侧的 timer/mod.rs 的 apply_settings 是关键它更新内存中的设置副本并且仅在空闲态!s.is_running s.elapsed_secs 0才调用self.reconfigure()重配引擎运行或暂停中则保留当前倒计时新时长在下一轮或手动重置后生效——这与 spec 的「运行中改时长下一轮生效」完全一致。前端的onTimerReset监听见 ipc/index.ts接收该事件并更新表盘。七、统计视图修正专注时长四舍五入到分钟7.1 问题与决策秒级时长引入后统计视图的「每日专注时长」不能再简单地截断取整。spec 明确每日专注时长应四舍五入到最近分钟而非截断。339 秒5:39的会话应计为 6 分钟而不是 5 分钟。验收场景当日完成工作会话合计 339 秒5:39→ 显示6m合计 324 秒5:24→ 显示5m余数 24 30 向下舍入恰好 1500 秒25:00→ 显示25m整数分钟边界不变。7.2 源码实现db/queries.rs 的 get_daily_stats() 中focus_mins由截断改为四舍五入focus_mins: ((focus_secs 30) / 60) as u32,(focus_secs 30) / 60是典型的整数四舍五入技巧余数 ≥ 30 秒时进位 30 秒时舍去。对应测试focus_mins_rounds_to_nearest_minutequeries.rs用内存数据库分别断言 339 s → 6 min、324 s → 5 min、1500 s → 25 min 三种边界。八、风险与权衡来自 design.mddesign.md 的Risks / Trade-offs记录了三条值得注意的取舍重置默认值的既有测试原测试通过读取time_work_mins断言重置后time_work_secs 25 * 60。迁移后测试必须改用time_work_secs作为播种与断言键——这是顺理成章的更新已在 settings/mod.rs 落实迁移不可逆如果用户降级到迁移前的版本应用会因缺少*_mins键而回退到Settings::default()。默认值本身合理因此是安全的但用户自定义值会丢失对桌面应用可接受已在迁移注释中说明MM:SS 解析边界情况如1:60、0:30、90:01统一由钳制处理不需要用户可见的错误状态。另外design.md 的Non-Goals明确划定了边界不做亚分钟精度的滑块滑块保持 1 分钟步进精细输入交给键盘不改变计时引擎消费秒的方式引擎本就在秒级工作暂不对MM:SS格式做本地化。九、改造任务清单与验证路径tasks.md 把整套改造拆解为 4 个模块、9 项验证全部已勾选完成模块关键动作1. DB 迁移Rust新增MIGRATION_2run()加if version 2defaults.rs 改秒值load()去* 60更新并新增迁移测试2. 前端 IPC 更新TimerSection.svelte的handleChange键名改为*_secs滑块oninput传valueAsNumber * 603. 可编辑徽章组件parseMMSS/formatMMSS工具函数静态span换input typetextoncommitEnter/Tab/blur逻辑聚焦全选视觉一致性样式4. 统计取整修正Rustget_daily_stats()改((focus_secs 30) / 60)新增 339/324 秒取整测试验证手段包括cargo test --manifest-path src-tauri/Cargo.tomlRust 全量测试、npm run checksvelte-check 零错误以及 9 项手工冒烟测试输入5:39重启后计时器从 5:39 开始、拖到 30 徽章显示30:00、0:10钳制为1:00、abc回退旧值、全新安装默认 25:00/5:00/15:00、空闲态改时长表盘即时更新、完成 5:39 会话后统计显示6m。十、实战要点速查输入格式MM:SS或裸整数分钟2525:00提交时机为 Enter / Tab / 失焦合法范围60 秒1:00 5400 秒90:00越界自动钳制无法解析则回退旧值存储单位数据库一律存整秒键名为time_work_secs/time_short_break_secs/time_long_break_secs默认值 1500 / 300 / 900迁移版本schema_version记录在案MIGRATION_2 幂等且事务包裹降级时缺失键回退默认值同步规则滑块按整分钟步进、以秒保存徽章精确到秒、滑块取Math.round(secs / 60)统计口径专注分钟数采用(focus_secs 30) / 60四舍五入。对于希望在自己的 Tauri 应用里实现「滑块粗调 键盘精调 秒级持久化」同类能力的开发者这套 proposal → spec → design → tasks → 源码与测试的完整链路本身就是一份可复用的工程范本。赞分享【免费下载链接】pomotroid:tomato: Simple and visually-pleasing Pomodoro timer项目地址https://gitcode.com/gh_mirrors/po/pomotroid点击查看免费下载相关推荐Pomotroid 计时器时长键盘输入MM:SS改造从分钟级滑块到秒级精度存储的完整实现Pomotroid 计时器时长键盘输入MM:SS改造从分钟级滑块到秒级精度存储的完整实现 本技术指南以 Pomotroid 开源仓库中「计时器设置键盘输入material-components-android 时间选择器MaterialTimePicker开发实战从拨盘到键盘输入的完整指南material components android 时间选择器MaterialTimePicker开发实战从拨盘到键盘输入的完整指南 Time picUI组件移动开发设计系统LoveDOS游戏开发实战打造经典像素风格的平台跳跃游戏LoveDOS游戏开发实战打造经典像素风格的平台跳跃游戏 LoveDOS是一款基于Lua的2D DOS游戏开发框架让开发者能够轻松创建复古风格的像素游戏。本游戏开发上一篇【热门开源项目下载】WanJuan3.0下一篇DeepTutor安装与本地部署指南4行命令跑通AI学习助手第一次就生成互动教材创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考