辩论赛计时器（DebateTimer）

版本：3.0.3 | 作者：Chen Yu | 许可证：GPL-3.0

DebateTimer 是一款基于 Electron 的离线桌面辩论赛计时器，提供编辑器与计时两种视图，支持导出为独立 Windows 安装程序以便比赛现场脱机使用。

破坏性变更 / Breaking Changes（3.0.0）

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 切换持方（仅对单边计时有效）

打包与发行

项目内置 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 中的真实版本号。运行该安装程序会：

1. 检测旧版本并提示卸载
2. 按用户选择目录安装
3. 创建桌面快捷方式和开始菜单文件夹
4. 安装完成后自动启动计时器

目标电脑无需安装 Node.js 或 NSIS。

发布流程

通过推送符合 v* 格式的 Git 标签触发 GitHub Actions 自动发布：

git tag v3.0.3
git push origin v3.0.3

工作流 .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.