89 lines
4.0 KiB
Markdown
89 lines
4.0 KiB
Markdown
# Time
|
||
|
||
轻量 Electron 桌面应用：巨字时钟 + 多闹钟 + 番茄钟 + 通用倒计时，顶栏 + 4 个标签挤在同一个 ~440×400 小窗口里。
|
||
|
||
- **巨字时钟** —— `HH:MM:SS` 24 小时制；首页另含日期、下一闹钟、番茄 / 倒计时状态、已启用闹钟数
|
||
- **多闹钟** —— 支持 `once` / `daily`，列表按本地时刻升序；`once` 响过后自动停用，`daily` 保留并排到下一天同刻
|
||
- **番茄钟** —— `25 / 5 / 15` 三段式，每完成 4 轮 focus 后插一个长休；可暂停 / 继续 / 跳过 / 重置；底部展示今日完成数
|
||
- **通用倒计时** —— `HH:MM:SS` 自由设置，自动记住上次时长；归零后弹“完成”按钮，8 秒无操作自动收起
|
||
- **6 套皮肤** —— Linear Dark、黄铜暗色、Solarized、Nord、Catppuccin Mocha、Vercel Light
|
||
- **4 张浮窗** —— 时钟 / 番茄钟 / 闹钟 / 倒计时各自一个独立 BrowserWindow；启动期预创建 + `hide`，点击瞬开；用户拖过的位置会记住
|
||
- **系统集成** —— 顶栏（4 个浮窗 toggle + 图钉置顶 + 齿轮）、托盘菜单、单实例锁、写盘失败 toast、主窗几何持久化、多显示器越界回退
|
||
|
||
提醒统一走系统通知（`Notification` API）。
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 用户
|
||
|
||
1. 下载安装包或便携版（见 [打包](#打包)）
|
||
2. 首次启动若被 Windows SmartScreen 拦截，点「更多信息 → 仍要运行」
|
||
3. 顶栏右侧依次是 4 个浮窗 toggle、图钉（置顶）、齿轮（设置）；主面板 4 个标签：**时钟 / 番茄钟 / 倒计时 / 闹钟**
|
||
4. 浮窗右键 / 双击 / Esc / × / 触屏长按 都能关
|
||
|
||
### 开发者
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev # electron-vite + HMR
|
||
npm run typecheck # node + web 两份 tsconfig 都过一遍
|
||
npm run build # 构建产物到 out/
|
||
npm run package # 打包 → release/（NSIS 安装包 + portable 单文件）
|
||
```
|
||
|
||
需要 Node.js 20+。
|
||
|
||
---
|
||
|
||
## 键盘交互
|
||
|
||
| 范围 | 按键 | 行为 |
|
||
|---|---|---|
|
||
| 浮窗 | `Esc` | 关闭（实际是 hide，预创建 BrowserWindow 不销毁） |
|
||
| 主窗标签条 | `←` / `→` | 切换上一个 / 下一个标签 |
|
||
| 主窗标签条 | `Home` / `End` | 跳到第一个 / 最后一个标签 |
|
||
| 闹钟 / 倒计时编辑器 | 滚轮 / `Shift` + 滚轮 | 时间步进 ±1 / ±5 |
|
||
|
||
---
|
||
|
||
## 数据存储
|
||
|
||
Windows 上是 `%APPDATA%/time/`（macOS / Linux 类似路径）：
|
||
|
||
- `app-state.json` —— 主状态（闹钟 / 番茄钟 / 倒计时 / 设置）
|
||
- `window-state.json` —— 主窗位置、大小（同步 `writeFileSync` 落盘）
|
||
|
||
`app-state.json` 写盘走 300ms 防抖 + 合并同批次 + `.tmp → rename` 原子提交；版本不匹配或解析失败时复制为 `.bak-v1` 后回退默认状态。`window-state.json` 不参与备份。
|
||
|
||
落盘前会剥离 `pomodoro.active` / `countdown.active` —— 重启后回到 idle，避免“旧 endsAt 已过期”的假象；闹钟的 `active=enabled` 完全持久化，重启后调度器按规则继续排程。
|
||
|
||
---
|
||
|
||
## 打包
|
||
|
||
```bash
|
||
npm run package
|
||
```
|
||
|
||
产物落在 `release/`：
|
||
|
||
- `Time Setup <version>.exe` —— NSIS 安装包（当前用户安装，可改安装目录）
|
||
- `Time-<version>-portable.exe` —— 免安装单文件
|
||
|
||
`productName = Time`，`appId = com.guan.time`，当前版本 `0.1.0`。未配置代码签名与自动更新。
|
||
|
||
---
|
||
|
||
## 已知限制
|
||
|
||
- 仅本地时区，UI 仅中文
|
||
- 未配置代码签名 —— 首次启动会被 SmartScreen 拦截
|
||
- macOS / Linux 标题栏已分支（macOS `hiddenInset` / Linux 系统 `default`），但仅在 Windows 上完整验证过打包
|
||
- 提醒只走系统通知；若系统级关闭了通知，闹钟 / 番茄钟阶段切换 / 倒计时归零都不会响
|
||
- 闹钟重复仅支持 `once` / `daily`；没有工作日 / 每周指定日
|
||
- 闹钟仅按本地时刻升序排列，**没有拖拽重排**
|
||
- 番茄钟持久化的 30 天完成历史（`byDate`）当前不展示在 UI 上；面板只显示今日完成数
|
||
- 没有“全局重置应用”入口 —— 只能分别重置番茄钟 / 倒计时到 idle
|