版本：3.1.0 | 作者：Chen Yu | 许可证：GPL-3.0
DebateTimer 是一款基于 Electron 的离线桌面辩论赛计时器，提供编辑器与计时两种视图，支持导出为独立 Windows 安装程序以便比赛现场脱机使用。
3.0.0 引入不兼容的配置 schema 变更与导出方式调整，首次启动时旧配置会自动迁移并备份，无需手动干预：
- 配置自动迁移：旧版
config.json（无version字段或version < 3）会在首次启动时自动迁移到version: 3格式。迁移前系统会将原始配置备份为config.json.v2.bak（位于用户数据目录）。 - 字段变更：
theme.backgroundImageSettings.scale已被移除并拆分为scaleX与scaleY；迁移函数会自动将旧scale值复制到scaleX/scaleY。 - 导出方式：WinRAR SFX 导出已正式移除；独立计时器导出仅支持 NSIS 安装包。
- 所见即所得编辑界面：直接在计时器预览中编辑所有文本元素，支持点击修改内容/字体/字号/颜色，拖动调整位置
- 赛事配置：编辑赛事名称、正反方队伍与辩题
- 环节管理：支持无计时、单边计时、单边发问、中立计时、双边对辩等多种环节类型；可自由增删改环节、调整顺序
- 名称模板：通过"持方 + 辩位 + 模板名称 + 附加项"快速生成规范环节名
- 主题样式：
- 自定义单个颜色（正反方色、中立色、标题色、背景色）
- 支持纯色/渐变/图片三种背景类型，图片支持透明度、缩放、XY偏移
- 调整字体（系统字体）与字号缩放
- 支持上传自定义 TTF/OTF 字体文件（仅用于文本显示）
- 状态栏支持高度拖拽和颜色/透明度/渐变自定义
- 导入/导出配置：将当前比赛配置保存为 JSON 文件，或从外部 JSON 文件导入配置；支持背景图片 Base64 硬编码
- 导出独立计时器：将当前配置与 Electron 运行时打包为单个安装程序 EXE，双击后按向导安装到本地，自动创建桌面和开始菜单快捷方式，安装完成后直接启动；赛前可修改队伍名称与辩题，不可修改其他配置。安装包版本号与元数据统一使用
package.json中的真实版本号。无需目标电脑安装 Node.js - 自动更新：集成
electron-updater，启动时自动检测 GitHub Releases 新版本并提示安装 - 跨平台构建配置：除 Windows NSIS/Portable 外，同时配置 macOS（dmg / zip）与 Linux（AppImage）分发目标
- GitHub Actions 自动发布：推送
v*标签即可触发工作流自动构建并上传分发包到 Release - 安装包体积优化：清理
vendor/nsis非必需目录并裁剪 Electron 运行时，减小最终分发包体积 - 计时控制：启动/暂停、停止、重置、切换环节、环节跳转、设置时间、切换持方、全屏、音效试播等
- 现代化界面：玻璃拟态卡片、底部悬浮胶囊控制面板、数字倒计时进度条、Toast 通知系统
- 完全离线：不依赖任何外部 CDN 或网络资源，所有字体使用系统字体
- Electron 42.x
- 原生 HTML / CSS / JavaScript（无框架、无构建工具）
- Web Audio API 提示音（零外部音频文件）
- NSIS（Nullsoft Scriptable Install System）独立计时器安装包生成
electron-updater自动更新- CommonJS（主进程）+ 全局脚本（渲染进程）
preload.js安全 IPC 桥接（遵循 Electron 安全最佳实践）
npm install
npm start首次启动会打开编辑页。修改配置后点击"保存配置"即可进入计时页；点击计时页控制面板的"返回(B)"可回到编辑页。也可直接点击"进入计时页"在不保存的情况下预览计时效果。
编辑页采用左侧导航栏 + 右侧内容面板布局。
- 编辑界面：
- 直接嵌入完整的计时器预览，所见即所得
- 点击文本元素（队伍名称、辩题、赛事名称等）弹出浮动工具栏，可编辑内容、字体、字号、颜色
- 拖动文本元素可调整位置，对称元素（正反方）自动同步移动
- 状态栏底部拖拽手柄可调整高度，点击空白处编辑颜色/透明度/渐变
- "修改背景"按钮进入背景编辑模式，支持纯色/渐变/图片三种类型
- 背景图片支持透明度、缩放、XY偏移，以 Base64 编码存储到配置中
- 环节管理：
- 环节管理面板采用左侧固定边栏 + 右侧可滚动列表布局
- 左侧边栏包含：
- 导航栏：纵向列出所有环节，支持鼠标拖拽排序，左键拖拽时选中项虚化，跟随鼠标显示放大倾斜预览，其他项自动滑动让位，并显示蓝色发光占位条
- 快捷操作：
+ 无计时/+ 陈词/+ 质询/+ 中立计时/+ 对辩/+ 自由辩论按钮始终可见，不受列表滚动影响 - 右键菜单：在导航栏任意环节上右键可执行：定位到该环节 / 上移 / 下移 / 删除
- 在环节卡片中修改名称、类型、时长与持方
- 使用名称模板下拉框快速生成规范名称，点击"确认名称"应用
- 通过"上移/下移/删除"调整环节顺序或移除环节
- 导入/导出：
- 导入配置：从 JSON 文件加载比赛配置，自动校验字段，自动迁移旧版配置
- 导出配置：将当前完整配置保存为 JSON，包含所有布局、状态栏、背景设置，便于备份或分享
- 导出独立计时器：生成一个 NSIS 安装程序 EXE，双击按向导安装后即可启动；打开后仅允许修改队伍名称与辩题
- 顶部操作栏：包含保存配置、重置默认、导入配置、导出配置、导出独立计时器、进入计时页等按钮
- 顶部全宽状态栏：左侧显示正方队伍（红色背景）+ 辩题，右侧显示反方队伍（蓝色背景）+ 辩题，中间显示赛事名称。状态栏高度和颜色可在编辑页自定义
- 中央显示赛事名称、当前环节名称
- 单边计时显示单个大型倒计时器，颜色随持方变化（正方红 / 反方蓝 / 中立白）
- 双边对辩显示正反方两个独立倒计时器，颜色区分
- 中立计时显示单个大型白色倒计时器，用于中场暂停或评委限时述票，不区分正方反方
- 无计时环节以超大字号展示环节名称，不显示计时器
- 进度条：单边计时和中立计时模式下数字下方显示进度条，最后 30 秒变黄，最后 5 秒变红并脉冲闪烁
- 控制面板：底部居中悬浮胶囊，半透明 + 毛玻璃背景，分组按钮（主控/导航/操作/音效/系统），hover 显示快捷键提示
- 快捷键：
Space启动/暂停（双边计时为切换发言方）P暂停Q/W/E试播 30 秒/5 秒/结束提示音F全屏B返回编辑页（独立运行时为"队伍设置"）←/→切换环节C切换持方（仅对单边计时有效）
在提交代码或发起 Pull Request 前，建议在本地依次执行以下检查，确保代码风格、测试与语法正确：
# 1. 代码风格检查
npm run lint
# 2. 运行测试
npm test# 3. 检查主进程与核心模块语法
node --check main.js
node --check js/timer-core.js
node --check js/editor-app.js
node --check js/timer-app.js
node --check js/main/ipc.js
node --check js/main/windows.js
node --check js/main/export.js
# 4. 打包验证（不发布）
npx electron-builder --publish never以上步骤与 .github/workflows/ci.yml 中的持续集成流程保持一致。
项目内置 electron-builder 配置，支持以下分发目标：
- Windows：NSIS 安装包（64-bit）、便携版（Portable）
- macOS：dmg / zip
- Linux：AppImage
生成分发包：
npm run dist构建输出位于 dist/ 目录（安装包命名会包含版本号）。
DebateTimer 3.0.0 集成 electron-updater，启动时会检查 GitHub Releases 中的最新版本。若存在新版本，将提示用户下载并安装更新。
在编辑页点击“导出独立计时器”，应用会将当前配置和 Electron 运行时打包为一个 NSIS 安装程序 EXE。安装包版本号与元数据统一使用 package.json 中的真实版本号。运行该安装程序会：
- 检测旧版本并提示卸载
- 按用户选择目录安装
- 创建桌面快捷方式和开始菜单文件夹
- 安装完成后自动启动计时器
目标电脑无需安装 Node.js 或 NSIS。
通过推送符合 v* 格式的 Git 标签触发 GitHub Actions 自动发布：
git tag v3.1.0
git push origin v3.1.0工作流 .github/workflows/release.yml 会自动执行 npm ci 与 npm run dist，并将 dist/ 下的 .exe、.blockmap、.yml、.zip 文件上传到对应版本的 GitHub Release 中。
.
├── main.js # Electron 主进程（窗口管理、IPC、配置持久化、日志、EXE 导出、自动更新）
├── preload.js # 渲染进程 IPC 安全桥接
├── editor.html # 编辑页（所见即所得预览 + 环节管理）
├── timer.html # 计时页
├── js/
│ ├── audio.js # Web Audio API 提示音生成（零外部音频文件）
│ ├── timer-core.js # 计时引擎核心（计时逻辑、状态管理）
│ ├── timer-app.js # 计时页 UI 控制（渲染、快捷键、主题应用）
│ ├── editor-app.js # 编辑页逻辑（预览交互、文本编辑、背景编辑、环节管理、拖拽排序）
│ └── toast.js # Toast 通知系统 + 自定义确认对话框
├── styles/
│ ├── variables.css # CSS 变量系统 + 通用组件（Toast、模态框、按钮、卡片）
│ ├── editor.css # 编辑页样式（预览区域、浮动工具栏、侧边栏、环节卡片、拖拽排序、响应式）
│ └── timer.css # 计时页样式（顶栏、计时器、进度条、控制面板、模态框）
├── vendor/
│ ├── embedded-binaries.js # 嵌入的 Electron 默认图标
│ └── nsis/ # 内置 NSIS 编译器（用于应用内导出独立计时器安装包）
├── .github/
│ └── workflows/
│ └── release.yml # GitHub Actions 自动发布工作流
├── package.json
├── README.md
├── CHANGELOG.md # 版本变更日志
├── .gitignore
├── .npmrc
└── LICENSE # GPL-3.0
GPL-3.0
© Chen Yu 2026 All rights reserved.