# WebTimer

**Repository Path**: nixius/web-timer

## Basic Information

- **Project Name**: WebTimer
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-20
- **Last Updated**: 2026-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Timer · 网页版（单文件 `WebTimer.html`）

一个**纯前端的计时工具**：模拟时钟 / 数字时钟 / 倒计时 / 正计时四大模块，浅色与深色两套主题、可自选强调色、环形进度、打点记录与导出。

整个程序只有**一个 HTML 文件**（约 147 KB，4400 余行），把 HTML、CSS、JavaScript、图标、提示音全部内联在里面：

* **不需要任何后端**，不需要起本地服务器；
* **不需要联网**，零外部请求（没有 CDN、没有 Web Font、没有图片和音频文件）；
* **双击即用**，也可以直接拖进浏览器，或放到 U 盘 / 内网机器 / 离线终端上运行。

> 本项目由桌面版 [Timer 项目](https://gitee.com/nixius/Timer) 逐模块移植而来，界面结构、配色规则、交互与配置项都尽量保持一致；窗口相关能力（置顶、无边框、系统贴靠等）在浏览器中无法实现，按要求忽略。

---

## 一、程序截图

| 模拟时钟 | 模拟时钟（深色 + 日期） |
| --- | --- |
| ![模拟时钟](screenshots/模拟时钟.png) | ![模拟时钟-深色](screenshots/模拟时钟-深色.png) |

| 数字时钟（深色） | 倒计时 |
| --- | --- |
| ![数字时钟](screenshots/数字时钟-深色.png) | ![倒计时](screenshots/倒计时.png) |

| 正计时 | 倒计时：收起侧栏，计时区占满 |
| --- | --- |
| ![正计时](screenshots/正计时.png) | ![收起侧栏](screenshots/倒计时-收起侧栏.png) |

| 倒计时结束提醒 | 导出打点记录 |
| --- | --- |
| ![结束提醒](screenshots/倒计时-结束提醒.png) | ![导出](screenshots/导出打点记录.png) |

| 双击记录写备注 | 关于 |
| --- | --- |
| ![打点备注](screenshots/打点备注.png) | ![关于](screenshots/关于.png) |

---

## 二、快速开始

| 方式 | 操作 |
| --- | --- |
| 最简单 | 双击 `WebTimer.html`，用系统默认浏览器打开 |
| 拖拽 | 把文件拖进已打开的 Chrome / Edge 窗口 |
| 命令行 | `chrome.exe "file:///D:/AI_Buddy/WebTimer/WebTimer.html"` |

首次打开即用，无需安装依赖、无需配置。所有设置（主题、强调色、预设、分栏比例等）自动保存在浏览器本地，下次打开自动恢复。

**运行环境**

| 项目 | 要求 |
| --- | --- |
| 浏览器 | Chrome / Edge（Chromium）**57 及以上**。代码面向 Windows 7 + Chrome 80 的目标环境编写：脚本只用 ES5 语法，CSS 只用 Chrome 57 时代以内就有的特性，并已逐项做过兼容性扫描（见 5.3） |
| 网络 | **完全不需要**（离线自检见第六节） |
| 磁盘 | 单个 HTML 文件，可放在任意目录、U 盘、只读介质 |
| 字体 | 只用系统自带字体：数字用 `Ubuntu Mono → Cascadia Mono → JetBrains Mono → Consolas → Menlo → Courier New` 等宽栈，中文回退到 `Microsoft YaHei / PingFang SC / Noto Sans CJK SC` 等，无需下载字体 |

---

## 三、功能特性

| 模块 | 主要功能 |
| --- | --- |
| **模拟时钟** | 表盘 / 12 整点刻度 / 60 分钟刻度、时针 / 分针 / 秒针、秒针毫秒级平滑走字、中心圆点与指针尾巴、表盘内日期与星期（可关）；秒针、平滑走字、日期三个开关直接点 |
| **数字时钟** | 大字号时间（字号随窗口自动缩放、永不溢出）、日期 + 中文星期、12/24 小时制切换、冒号闪烁（不显示秒时自动失效） |
| **倒计时** | 快速预设按钮、自定义时长输入（`HH:MM:SS` / `MM:SS` / 纯数字分钟 / `1h30m` / `1小时30分`）、开始 / 暂停 / 继续 / 重置、环形进度、结束提示音 + 数字闪烁 + 标签页标题闪烁 + 提醒弹窗、最后 10 秒进度环转警示红、计时中随时打点 |
| **正计时** | 从 `00:00:00` 累加、开始 / 暂停 / 继续 / 重置、环形进度按 60 秒一圈扫动（相当于放大的秒针）、打点（Lap） |
| **打点记录** | 序号 / 相对时间 / 绝对时间 / 与上次间隔；最新一条置顶并高亮；按「记录」分组着色；空态提示；**双击条目写文字备注**；右键菜单（编辑备注 / 清除备注 / 复制该行 / 复制全部 / 删除该行）；清空（二次确认）；导出 CSV / TXT（含备注列） |
| **分栏与折叠** | 计时页左右分栏，可拖动中间分隔条调整比例（比例写回设置）；计时区右上角悬浮箭头可一键收起右侧面板让计时区占满窗口，收起后该处补齐**开始 / 打点 / 重置**入口 |
| **主题** | 浅色（默认）/ 深色实时切换；色盘自选强调色，强调色统一作用于导航选中态、按钮、时钟指针与刻度、进度弧、打点按钮、输入框聚焦边框、表格高亮等；**自定义的颜色在切换深浅主题时保留** |
| **快捷开关** | 时钟页底部「秒针 / 平滑走字 / 日期」「24 小时制 / 秒 / 冒号闪烁 / 日期」，倒计时页「毫秒 / 提示音 / 结束弹窗」，正计时页「毫秒」——点一下即生效 |
| **自适应** | 窗口任意缩放不变形（表盘、圆环、字号都按可用空间实时计算）；窄窗口下导航自动切成只显示图标 |

**几个交互细节**

* **计时精度**：倒计时与正计时都基于「已累计秒数 + 本次启动时的时间戳」计算，不靠定时器累加，因此标签页被降频、窗口最小化都不会产生累计误差；回到前台会立即补一次刷新。
* **倒计时显示按秒向上取整**：刚开始显示 `00:05:00`，满 1 秒后才变 `00:04:59`；最后一秒显示 `00:00:01`，真正走完才是 `00:00:00`（勾选「毫秒」后按真实毫秒连续显示，不做取整）。
* **收起侧栏后打点有反馈**：记录卡片看不见时，会在计时区下方弹出一条轻提示（`已打点 00:00:12（第 3 条）`），避免「点了没反应」的错觉。
* **重置**：若已有打点记录，会先问「取消 / 仅重置计时 / 重置并清空记录」；选择保留记录时，「重置」按钮保持可用（随时能再清空）。
* **提醒不打断**：倒计时结束的提醒弹窗可以叠加显示（比如确认框还开着时倒计时走完，结束提醒会叠在上面，关掉后确认框仍在等待选择）。

### 快捷键

| 快捷键 | 作用 |
| --- | --- |
| `Space` | 当前页面打点（输入框获得焦点时正常输入空格） |
| `Ctrl+1` ~ `Ctrl+4` | 依次切换到 模拟时钟 / 数字时钟 / 倒计时 / 正计时 |
| `Esc` / `Enter` | 关闭对话框 / 确认对话框默认按钮 |

---

## 四、设置与配置

网页版把桌面版的 `config.json` 换成浏览器本地存储，**结构、默认值、校验规则完全一致**（深度合并 + 类型校验 + 取值兜底 + 主题配色同步）。

| 项目 | 说明 |
| --- | --- |
| 存储位置 | `localStorage`，键名 `timer.config.v1` |
| 存储不可用时 | 自动退化为内存存储（功能不受影响，只是设置不跨刷新保留） |
| 恢复默认 | 浏览器开发者工具控制台执行 `localStorage.removeItem("timer.config.v1")` 后刷新页面 |
| 在线修改 | 控制台执行 `Config.set("theme.accent_color", "#FF9800")`、`Config.set("countdown.presets", [{label:"番茄钟", seconds:1500}])` 等，立即生效并保存 |

主要配置项（节选，与桌面版一致）：

| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| `theme.mode` | `"light"` | 浅色 / 深色 |
| `theme.accent_color` | `"#386338"` | 强调色（浅色主题）；深色主题默认 `#8FBC8F` |
| `clock.hour_format` | `24` | 12 / 24 小时制 |
| `clock.smooth_second_hand` | `true` | 秒针平滑走字 |
| `clock.analog.show_seconds` / `show_date` | `true` / `false` | 模拟时钟的秒针与日期（与数字时钟互相独立） |
| `clock.digital.show_seconds` / `blink_colon` / `show_date` | `true` / `false` / `true` | 数字时钟的秒、冒号闪烁、日期 |
| `countdown.presets` | 5/10/20/30/45 分钟、1 小时 | 预设按钮，可自由增删改 |
| `countdown.show_milliseconds` | `false` | 显示 `HH:MM:SS.mmm` |
| `countdown.sound_enabled` | `true` | 结束播放提示音 |
| `countdown.popup_on_finish` | `true` | 结束弹出提醒 |
| `countdown.side_panel` | `true` | 倒计时右侧面板默认展开 |
| `countdown.split_ratio` | `0.0` | `0` = 自动（侧栏取最小可用宽度），拖动分隔条后写入 `0.40~0.92` |
| `stopwatch.show_milliseconds` | `false` | 正计时显示毫秒 |
| `stopwatch.lap_enabled` | `true` | 是否启用打点（界面上不提供开关，只能改配置） |
| `stopwatch.side_panel` | `false` | 正计时默认收起侧栏，专注计时 |

非法值不会让程序出错：颜色格式错误回退预设色、小时制非 12/24 回退 24、预设列表会过滤掉非法条目、分栏比例收敛到合法区间。

---

## 五、技术实现

### 5.1 文件结构

```text
WebTimer.html          ← 全部内容：HTML + CSS + 原生 JS（无外部文件）
├─ <style>             主题 token（CSS 变量）+ 全部界面样式
├─ <body>              顶栏、四个页面、计时卡片骨架
└─ <script>            ① 颜色/配置/存储  ② 时间格式化  ③ 图标(SVG)
                       ④ 对话框/右键菜单 ⑤ 提示音(WebAudio)
                       ⑥ 打点表格  ⑦ 环形进度  ⑧ 两个时钟视图
                       ⑨ 倒计时/正计时状态机  ⑩ 分栏控制  ⑪ 应用装配
```

### 5.2 与桌面版的模块对照

| 桌面版（PySide6） | 网页版实现 |
| --- | --- |
| `app/utils/colors.py` | 同一套颜色算法：HEX 校验、变亮/变暗/混色、相对亮度与对比色、`elevate / recess / surface` 推导 |
| `app/theme.py` | 「5 个基础色 → 全套界面 token」推导后写入 CSS 变量，界面样式全部引用变量，切主题只改变量 |
| `app/config.py` | 同样的默认值表 + 深度合并 + 类型校验 + 预设清洗 + 主题配色同步；`localStorage` 代替 `config.json` |
| `app/views/analog_clock.py` | **Canvas 2D** 矢量绘制：归一化到 200×200 逻辑方格、径向渐变表盘、刻度、数字、带尾巴的锥形指针、日期胶囊；按 `devicePixelRatio` 适配高分屏 |
| `app/views/digital_clock.py` | Canvas 绘制，字号按可用宽高自适应，12/24 小时制与上午/下午、冒号闪烁 |
| `app/widgets/progress_ring.py` | Canvas 画轨道与进度弧（从 12 点顺时针），文字层用 DOM 叠在环心，并按圆内接矩形约束字号 |
| `app/widgets/mark_table.py` | DOM 表格：最新置顶、按记录分组着色、备注行 `└` 连接符、右键菜单、CSV/TXT 导出 |
| `app/widgets/icons.py` | **内联 SVG** 图标（24×24 逻辑方格，`currentColor` 取色，随主题/悬停/选中自动变色） |
| `app/utils/sound.py` + `alert.wav` | **WebAudio 现场合成**同一段双音提示音（880 Hz + 1174.66 Hz，指数衰减 + 二次谐波），不依赖音频文件 |
| `app/views/timer_base.py` | 同样的状态机：`idle / running / paused` + 「累计秒数 + 时间戳」，`setInterval` 只负责刷新界面 |
| `app/main_window.py` | 顶栏三段式布局、导航切换、主题与强调色、对话框、快捷键（`Space` / `Ctrl+1~4`） |

### 5.3 关键实现点

* **计时与刷新解耦**：任何时刻的已用时间都由「累计值 + 时间戳差」实时算出，定时器只驱动重绘，所以精度不受标签页降频影响。
* **所有图形都是矢量的**：表盘、圆环、图标分别用 Canvas 与内联 SVG 绘制，任意缩放/高 DPI 都不模糊，也不依赖任何图片资源。
* **主题只有一个数据源**：基础色 → token → CSS 变量，避免同一套颜色散落多处而漂移。
* **配置写入即校验**：`Config.set()` 会按字段语义规范化（颜色、小时制、预设、比例、布尔），非法值回退默认，不写脏数据。
* **对话框做成栈**：后开的对话框叠在前面之上，`Esc`/`Enter` 只作用于栈顶；关闭时还会清理任何游离的遮罩层，保证不会出现「看不见但挡住点击」的覆盖层。
* **导出用 Blob + `a[download]`**：CSV / TXT 直接触发浏览器下载，文本加 UTF-8 BOM，Excel / 记事本打开不乱码。
* **面向老浏览器**：全部脚本只使用 `var` / `function` / 原型继承，避免箭头函数、模板字符串、`class`、可选链、`String.replaceAll`、`ctx.roundRect` 等新语法；CSS 避免 flex `gap`、`inset` 简写、`:is()/:where()`、`aspect-ratio` 等特性（用 margin、`grid gap`、四向定位替代）。

---

## 六、离线与受限环境验证

**静态检查**：全文没有任何外部引用——没有 `<script src>`、`<link href>`、`<img>`、`@import`、`url(...)`、`fetch` / `XMLHttpRequest` / `WebSocket`；图标是内联 SVG，站点图标是 `data:` URI，提示音是 WebAudio 现场合成，字体只用系统字体栈（无 `@font-face`）。

**运行验证**（无头 Chromium 中真实加载并驱动）：

| 场景 | 条件 | 结果 |
| --- | --- | --- |
| 完全离线 | DNS 全部阻断（`MAP * ~NOTFOUND`）+ 指向死代理 `127.0.0.1:1` + 注入只允许内联资源、禁止一切外部请求的严格 CSP | 44 项断言全部通过 |
| 能力受限 | 在上面的基础上再破坏 `localStorage` / `sessionStorage`（抛异常）、`AudioContext`、`URL.createObjectURL`、`document.execCommand`、`navigator.clipboard`、`ResizeObserver` | 44 项断言全部通过（优雅降级） |
| 中文 + 空格路径 | 放在 `离线 测试目录/计时器 WebTimer.html` 下离线打开 | 正常渲染与运行 |
| 功能回归 | 无头 Chromium 以**真实点击**（先命中测试再点击）驱动全部页面 | 46 项断言全部通过 |

**缺失能力时的降级行为**

| 能力 | 不可用时 |
| --- | --- |
| `localStorage` | 退化为内存存储：功能照常，只是设置不跨刷新保留 |
| WebAudio | 提示音静默跳过，计时与提醒不受影响 |
| Blob 下载 | 导出失败但不抛异常，界面继续可用 |
| 剪贴板 API | 回退到 `execCommand('copy')`；两者都不可用时复制操作静默失败 |
| `ResizeObserver` | 打点表格退化为在渲染时判断列宽（仍会自动隐藏「绝对时间」列） |

---

## 七、与桌面版的差异

| 项目 | 桌面版 | 网页版 |
| --- | --- | --- |
| 分发 | `Timer.exe` / PyInstaller 单文件 | 单个 `WebTimer.html` |
| 配置文件 | 程序同级目录 `config.json`（不可写时回退 `~/.timer/`） | `localStorage["timer.config.v1"]` |
| 窗口能力 | 置顶、无边框、自绘标题栏、边缘拉伸、`Win + 方向键` 贴靠、窗口阴影 | **按要求忽略**（浏览器不允许页面控制这些） |
| 结束提醒 | 弹窗 + 提示音 + 数字闪烁 + **任务栏闪烁** | 弹窗 + 提示音 + 数字闪烁 + **标签页标题闪烁** |
| 提示音 | 随包分发的 `alert.wav` | 同参数的 WebAudio 现场合成 |
| 字体 | 自带 Ubuntu Mono（打包进程序） | 使用系统等宽/中文字体栈 |
| 记忆窗口尺寸 | 关闭时写回配置 | 不适用（由浏览器决定） |

---

## 八、文件说明

```text
WebTimer.html                  成品：单文件网页版（双击即用）
README.md                      本文件
screenshots/                   README 中引用的界面截图
```

---

## 九、出处与许可

* 界面与交互参考同目录桌面版 `Timer/`（作者 chaos，MIT License）。
* 网页版为独立的纯前端实现，同样以 **MIT License** 发布，可自由使用与修改。