# handwrite-on-screen

**Repository Path**: newpc/handwrite-on-screen

## Basic Information

- **Project Name**: handwrite-on-screen
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Unlicense
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-16
- **Last Updated**: 2026-09-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 屏幕批注工具（Handwrite On Screen）

面向 Windows 的屏幕叠加手写批注工具。基于 Electron、Vue 3 和 Element Plus，适合网课、演示、会议讲解及数位板书写。

## 功能概览

- 进入/退出绘制叠加层
- 铅笔、画刷、直线、箭头、矩形、圆形、文字、激光笔、聚光灯和多种擦除工具
- 独立记忆工具粗细，支持颜色、透明度、压力感应和收笔平滑
- 撤销/重做、清屏、多页批注、显示/隐藏笔迹
- 新版 Dock 快速切换工具、颜色和粗细，支持停靠、自由拖动、横竖布局及按钮自定义
- 蓝白、深色等六套外观主题，自定义主题色与玻璃/卡片质感
- 透明直绘、桌面镜像和自动选择三种网页视频批注模式
- 导出当前页 PNG、笔迹 SVG、多页 PNG/PDF 或复制到剪贴板
- 自定义快捷键，配置修改后即时同步到启动器、Dock 和绘制层
- 按键拦截开关：仅拦截配置中的快捷键，不拦截其他按键（适配视频播放空格、左右键）
- 退出绘制时清屏与再次进入恢复上次笔迹的行为可配置
- 绘制会话自动保存，异常退出后可在设置中心恢复或丢弃
- 区域冻结：框选桌面区域并作为新页面底图继续批注
- 设置搜索、Dock 场景预设与自动收起、计时器迷你悬浮模式
- 统一历史文件中心，管理 PNG、SVG、PDF 和多页 PNG 导出

## 界面预览

### 设置与外观

![常规设置](./pic/settings-general.jpg)

常规页提供开机自启、启动方式、六套主题、主题色和背景质感设置。窗口尺寸与位置会在调整后自动保存。

### 画笔与工具

![画笔与工具](./pic/settings-tools.jpg)

画笔与工具页集中管理快速操作、默认工具、图形与演示工具、颜色板、粗细、压感和 Dock 直达按钮。

### 快捷键

![快捷键设置](./pic/settings-shortcuts.jpg)

快捷键页可录入、清空和恢复组合键，保存前会提示重复配置；若快捷键被系统或其他软件占用，也会显示注册失败状态。默认使用 `Control+Alt+D` 进入绘制、`Control+Alt+C` 清屏、`Escape` 退出绘制。

### 演示与导出

![演示与导出](./pic/settings-presentation.jpg)

演示与导出页用于设置 Dock 停靠位置、网页视频批注模式、绘制屏幕范围和保存时是否包含桌面背景，并可导出当前页 PNG、笔迹 SVG、多页 PNG/PDF 或复制到剪贴板。

![历史文件中心](./pic/settings-history.jpg)

历史文件中心统一展示各类导出结果，支持打开、定位、重命名显示名称、移除记录，以及将 PNG 作为新页面继续批注。

### 关于与帮助

![关于与帮助](./pic/settings-about.jpg)

关于页展示版本、构建渠道、许可证、作者、邮箱和仓库地址，并提供本地日志入口。“检查更新”当前标记为待实现。

![内置使用说明](./pic/help-guide.jpg)

内置说明覆盖进入与退出绘制、画笔与清理、Dock 操作、网页视频兼容模式、保存和诊断流程，可在软件内直接查看。

### 绘制 Dock

![新版绘制 Dock](./pic/dock-toolbar.jpg)

Dock 是绘制模式的常驻操作栏。进入绘制后仍保持在叠加层上方，可直接切换工具、颜色、粗细、页面以及执行撤销、清屏和保存。

![Dock 场景预设](./pic/dock-presets.jpg)

Dock 可直接应用课堂讲解、会议批注和自由书写预设；停靠模式还可按设定延迟自动收起。

### 计时器

![计时器工具](./pic/timer-tool.jpg)

计时器支持正计时、倒计时、暂停、继续、计次、停止和重置，可设置语音提醒间隔；计次列表占用窗口剩余空间并可独立滚动。“隐藏”保留状态，“关闭”停止计时并销毁窗口。

![倒计时目标设置](./pic/timer-countdown.jpg)

切换到倒计时后，可分别设置小时、分钟和秒；目标时间使用独立网格行，在紧凑窗口中也不会与模式切换或计时数字重叠。

![计时器迷你模式](./pic/timer-mini.jpg)

迷你模式仅保留状态、时间、启停、展开和隐藏操作，并记忆悬浮位置。

### 区域冻结

![区域冻结选择](./pic/region-freeze.jpg)

从快速操作、Dock“更多”菜单或 `Control+Alt+X` 启动区域冻结，拖动框选后会将截图作为新页面底图；按 `Escape` 取消。

### 使用场景

![网页批注示例](./pic/网页上看视频批注.jpg)

可在网页视频、PDF、WPS、OneNote 或客户端课程上方书写公式、演算步骤和重点标注，也可配合数位板快捷键快速进入绘制与清屏。

## 功能说明

- 绘制工具：铅笔、画刷、橡皮擦、直线、箭头、矩形、圆形、整笔擦除、框选擦除、激光笔、聚光灯、文字和选择工具。
- 画笔参数：颜色、`1-50 px` 粗细、透明度、压感和收笔平滑；常用工具可保存独立粗细，也可将当前组合保存为场景预设。
- 画布与页面：撤销、重做、清屏、隐藏/显示笔迹、多页新增与删除、选中对象缩放、复制和删除。
- Dock：进入/退出绘制、常用工具直达、完整工具菜单、颜色、粗细、计时器、页面、清屏、保存和位置设置。支持顶部、底部、左侧、右侧、自由拖动、横向/竖向布局，弹层靠近屏幕边缘时自动换向。
- Dock 自定义：在“画笔与工具”页选择直达按钮并调整顺序；Dock 颜色和外观跟随软件主题，绘制期间保持顶层和可点击。
- Dock 预设与收起：内置三套场景预设；顶部、底部、左侧和右侧停靠时可自动缩到屏幕边缘，悬浮后展开。
- 网页视频：自动选择、透明直绘和桌面镜像三种模式。镜像源只显示屏幕工作区，任务栏区域透出真实桌面以保持绘制前后坐标一致；受 DRM 保护的画面仍可能无法捕获。
- 多屏：可在全部屏幕、当前屏幕或指定屏幕绘制，每块屏幕使用独立画布。
- 外观：六套主题、自定义主题色、玻璃/清晰卡片/柔和磨砂质感；选择后立即同步到启动器和 Dock。
- 快捷键：点击字段直接录入组合键，支持恢复默认、重复检测和系统占用提示。
- 导出与历史：当前页 PNG、仅笔迹 SVG、复制到剪贴板、多页 PNG 和多页 PDF；成功导出后自动写入历史文件中心。
- 计时器：正计时、倒计时、计次、语音提醒、完整/迷你模式及独立快捷键，Dock 中可直接打开。
- 区域冻结：按显示器缩放比例截取工作区内区域，作为新的批注页继续编辑；受保护内容可能无法捕获。
- 会话恢复：页面、笔迹和底图变更后自动保存；正常退出标记为干净，异常退出时在下次启动提供恢复入口。
- 设置搜索：搜索页面、设置项、工具和快捷键名称，点击结果直接跳转并高亮目标区域。
- 系统与诊断：支持开机自启、启动显示偏好、窗口尺寸和位置记忆、本地日志及崩溃转储。
- 关于：展示版本、许可证、作者、邮箱和仓库地址。“检查更新”当前仅展示“待实现”，尚未连接更新服务。

## 使用指南

- 启动应用
  - 交互式调试菜单：`yarn dev` 或双击 `dev.bat`
    - 可选择单独启动某个模块进行调试
    - 选项包括：叠加层、启动器、侧边栏、工具页、所有模块、启动 Electron
  - 开发模式：`yarn start`
  - 本地测试安装包：`yarn dist:local`，使用当前版本构建且不会修改 `package.json`
  - 正式打包安装：`yarn dist`，自动递增 patch 版本并生成安装包
  - Windows 双击测试构建：`build-test.bat`，生成安装包但保持当前版本号
  - Windows 双击发布构建：`build-release.bat`，成功后自动递增 patch 版本号；失败时恢复原版本
- 绘制流程
  - 在启动器点击“进入绘制”，或使用自定义快捷键进入叠加层
  - 在叠加层上进行批注，移动鼠标可见工具光标，按下并拖动绘制
  - 点击“退出绘制”，或使用自定义快捷键退出
- 工具与参数
  - 工具切换：铅笔、画刷、橡皮擦
  - 粗细和颜色可在启动器或 Dock 调整，透明度可在启动器调整
  - 每种工具的粗细会单独持久化到配置文件的 `toolSizes` 中（铅笔/画刷/橡皮擦互相独立）
  - 切换不同工具时，启动器粗细滑块会自动切换到该工具的预设粗细
- 停靠栏（Dock）
  - 提供快速操作按钮与快捷键提示，系统命令只在悬浮或点击时显示主题色
  - 可直接调节 `1-50 px` 绘制粗细，并按工具保存粗细
  - 可在“画笔与工具”页选择 Dock 直达工具并调整顺序
  - 可从启动器切换到 Dock 模式
- 保存图片
  - 在启动器或 Dock 中点击“保存图片”，将当前画布导出为 PNG
- 窗口与交互
  - 启动器窗口可拖动、缩放，提供最小化、关闭与切换 Dock 的按钮
  - 启动器会保存最后一次窗口尺寸和位置，下次启动时恢复
  - 绘制时 Dock 保持在叠加层上方，可直接点击切换工具和参数

## 快捷键

- 默认快捷键（可在“自定义设置”中修改）：
  - 进入绘制：`Control+Alt+D`
  - 退出绘制：`Escape`
  - 撤销：`Control+Alt+Z`
  - 重做：`Control+Alt+Y`
  - 清屏：`Control+Alt+C`
  - 显示 Dock：`Control+Alt+T`
  - 保存图片：`Control+Alt+S`
  - 隐藏/显示笔迹：`Control+Alt+H`
  - 冻结屏幕区域：`Control+Alt+X`
  - 基础工具：铅笔 `Control+1`、画刷 `Control+2`、橡皮擦 `Control+3`
  - 图形与擦除：直线 `Control+4`、箭头 `Control+5`、矩形 `Control+6`、圆形 `Control+7`、整笔擦除 `Control+8`、框选擦除 `Control+9`
  - 演示与编辑：激光笔 `Control+Alt+G`、聚光灯 `Control+Alt+F`、文字 `Control+Alt+E`、选择 `Control+0`
  - 计时器：打开 `Control+Alt+I`、启停 `Control+Alt+P`、计次 `Control+Alt+L`、停止 `Control+Alt+O`、重置 `Control+Alt+R`
- 自定义与显示
  - 打开“自定义设置”，在输入框内直接按目标组合键进行录入
  - 支持清空（按 Delete/Backspace 或点击输入框的清除按钮）
  - 保存后立即写入配置并刷新页面按钮的快捷键信息
- 按键拦截开关
  - 开启时：仅拦截配置中的快捷键，不拦截其他按键（如空格、左右键用于视频控制）
  - 关闭时：不拦截任何按键，不注册全局快捷键

## 配置文件

- 路径：程序文件所在目录下的 `config.json`
  - 主进程在应用目录中创建并读取该文件（默认优先 `app.getAppPath()/config.json`，回退到 exe 同目录）
- 字段说明：
  - `shortcuts`: 快捷键映射对象
    - 绘制控制、全部工具切换、保存、笔迹显示和计时器操作均可独立配置
  - `clearOnDisable`: 退出绘制后是否清屏（默认 `true`）
  - `size`: 默认粗细（数值）
  - `color`: 默认颜色（十六进制，如 `#ff3366`）
  - `alpha`: 默认透明度（0~1）
  - `debug`: 是否开启调试模式（打开 DevTools）
  - `toolSizes`: 按工具保存的粗细 `{ pencil, brush, eraser }`，切换工具时将自动应用对应值
  - `interceptKeys`: 是否只拦截快捷键（默认 `true`）
  - `restoreOnEnable`: 再次进入绘制时是否恢复上次笔迹（默认 `false`）。开启后退出时会缓存当前笔迹，重新进入自动恢复。
  - `relaxTailMs`: 收笔压力平滑时间窗口，单位毫秒（默认 `200`）。用于数位板收笔时，如果最后一小段压力突然变大，将按起笔时的粗细绘制，避免尾部突然变粗。
  - `usePressure`: 是否启用压力感应粗细（默认 `true`）。关闭后将使用固定粗细绘制，不再根据压力变化调整线条宽度，可进一步避免收笔处出现粗点。
  - `videoCompatibilityMode`: 网页视频批注模式：`auto`（默认，按浏览器图形加速配置选择）、`transparent`（透明直绘）或 `mirror`（桌面镜像绘制）。
  - `uiTheme`、`uiAccent`、`uiTexture`: 软件主题、主题色和背景质感。
  - `openAtLogin`、`showDockOnStart`: 开机自启和启动时显示 Dock。
  - `dockPosition`、`dockFreeBounds`、`dockFreeOrientation`、`dockTools`: Dock 停靠/自由位置、横竖方向和直达工具列表。
  - `dockPresets`、`dockAutoHide`、`dockAutoHideDelayMs`: Dock 场景预设、自动收起和延迟时间。
  - `timer.displayMode`、`timer.miniBounds`: 计时器完整/迷你显示模式和迷你窗口位置。
  - `historyItems`: 导出历史元数据；移除记录默认不会删除磁盘文件。
  - `sessionRecovery.enabled`: 是否启用绘制会话异常恢复。
  - `boardMode`: 透明桌面、白色、浅色、黑板或网格画布。
  - `drawingDisplayScope`、`drawingDisplayId`: 全部、当前或指定屏幕的绘制范围。
- 示例：

````json
{
  "shortcuts": {
    "enableDraw": "Control+Alt+D",
    "disableDraw": "Escape",
    "undo": "Control+Alt+Z",
    "redo": "Control+Alt+Y",
    "clear": "Control+Alt+C",
    "toggleToolbar": "Control+Alt+T",
    "savePNG": "Control+Alt+S",
    "toggleStrokes": "Control+Alt+H",
    "tool_pencil": "Control+1",
    "tool_brush": "Control+2",
    "tool_eraser": "Control+3"
  },
  "clearOnDisable": true,
  "size": 8,
  "color": "#ff3366",
  "alpha": 1,
  "debug": false,
  "toolSizes": { "pencil": 6, "brush": 12, "eraser": 50 },
  "interceptKeys": true,
  "restoreOnEnable": true,
  "relaxTailMs": 200,
  "usePressure": false
}
````

## 编译与运行

- 环境依赖
  - Node.js ≥ 18（建议）
  - Yarn 1.x（项目使用 `yarn@1.22.11`）
- 常用脚本（`package.json` 中定义）：
  - 实时调试全应用：`yarn dev:debug` 或双击 `dev-debug.bat`
    - Vue/SCSS 改动通过 Vite HMR 自动更新已打开页面。
    - 修改 `src/main.ts` 或 `src/preload.ts` 后，脚本自动重建并重启 Electron。
    - 使用 `Ctrl+C` 一次关闭 Vite 与 Electron 子进程。
  - 更新 README 截图：先运行 `yarn dev:all`，再执行 `yarn capture:readme`
    - 自动采集蓝白主题的五个设置页、内置帮助、Dock 和计时器，并以压缩 JPEG 写入 `pic/`
    - 采集完成后恢复原主题和 Dock 位置
  - 开发运行主进程：`yarn start`
    - 构建主进程后启动 Electron，使用 `build/main.cjs`
  - 分模块开发与构建：
    - 启动器开发：`yarn dev:launcher`（Vite 开发服务器）
    - 启动器构建：`yarn build:launcher`
    - 叠加层开发：`yarn dev:renderer`
    - 叠加层构建：`yarn build:renderer`
    - Dock 开发：`yarn dev:dock`
    - Dock 构建：`yarn build:dock`
    - 主进程构建：`yarn build:main`
  - 打包发布：`yarn dist`
    - 打包前自动将 `package.json` 的 patch 版本加 1，构建失败会恢复原版本；成功后请把版本变更纳入发布提交
    - 使用 `electron-builder` 生成 Windows NSIS 安装包，默认产物位于 `dist/`
  - 本地测试打包：`yarn dist:local`
    - 使用 `package.json` 当前版本构建，不修改版本号，适合验证安装包和功能回归
  - 手动调整发布级别：`yarn dist:minor`（minor）或 `yarn dist:major`（major）；大版本和功能版本由发布者决定，日常修复使用自动 patch
- 安装包体积
  - 前端已打包的 `vue`、`element-plus` 和 `pdfjs-dist` 仅作为 `devDependencies`，不会重复进入安装包；主进程运行时只保留 `sql.js`
  - 安装包只包含 `build/`、四个页面的 `dist/`、运行时图标和 `package.json`，不再携带源码和开发缓存
  - electron-builder 只保留 `zh-CN` Chromium locale 并使用最高压缩级别，优先将 NSIS 安装包控制在 100MB 限制以内
- 图标
  - `assets/icon.svg` 是图标设计源，`assets/icon.ico` 用于 Windows 安装器、快捷方式和 Electron 窗口
  - 开发运行和打包运行的所有窗口、页面 favicon、安装器使用同一套资源
- 目录说明
  - `src/main.ts`：主进程入口、窗口管理、IPC 通信、配置读写、全局快捷键
  - `src/preload.ts`：隔离上下文的桥接 API（`window.overlay`）
  - `src/launcher`：启动器页面（Vue3 + Element Plus）
  - `src/renderer`：叠加层页面（画布绘制逻辑）
  - `src/dock`：右侧停靠栏页面
  - `build/`：主进程构建输出（CJS）
  - `dist/`：各前端页面构建输出与安装包产物
- 国内源（可选）
  - 若网络较慢，可设置国内镜像源：`yarn config set registry https://registry.npmmirror.com`
  - 可还原为默认源：`yarn config set registry https://registry.npmjs.org`

## 使用逻辑与架构简述

- 主进程
  - 初始化配置文件，广播初始参数（颜色、粗细、透明度、工具粗细等）
  - 根据 `interceptKeys` 注册/取消全局快捷键（仅注册配置中的快捷键）
  - 处理设置更新，写入 `config.json`，并广播 `ui:config` 到各窗口
  - 通过 `did-finish-load` 在窗口加载完成后主动推送配置，避免首次显示默认值
- 渲染层（叠加层）
  - 维护 `undoStack/redoStack` 存储笔迹；橡皮擦使用 `destination-out` 清除
  - 退出绘制时：若 `clearOnDisable=true` 缓存当前笔迹供恢复；否则不缓存
  - 再次进入绘制时：若 `restoreOnEnable=true` 且存在缓存，则恢复并重绘
- 多屏支持
  - 为每个显示器创建独立叠加层窗口；进入/退出绘制会同步所有叠加层
  - 未进入绘制时隐藏全屏叠加层，避免影响浏览器视频合成
  - 网页视频批注模式：透明直绘适合浏览器关闭图形加速或画中画；桌面镜像绘制采集当前屏幕的工作区并作为透明叠加窗口中的视频背景，任务栏区域由中性遮罩覆盖。镜像失败会自动回退透明桌面；自动模式只读取 Chrome、Edge、Chromium 的本机配置，不会修改浏览器设置
  - 绘制期间 Dock 使用高于叠加层的窗口层级，保持可见并可直接点击；退出绘制后恢复普通窗口层级
  - 绘制点由主进程同步系统光标位置，跨显示器移动时保持跟随；按住鼠标跨屏时笔划会转交给目标显示器继续绘制
- 粗细与工具

  - 工具切换时会根据 `toolSizes` 自动应用该工具的粗细；调整粗细会写回到配置中对应工具

- IPC 通道（部分）
  - 主进程 → 渲染层：`overlay:setDrawEnabled`、`overlay:setTool`、`overlay:setColor`、`overlay:setSize`、`overlay:initToolSizes`、`overlay:setAlpha`、`overlay:toggleToolbar`、`overlay:requestSavePNG`
  - 渲染层 → 主进程：`renderer:savePNG`、`renderer:announceSize`、`renderer:setToolSize`
  - 任意窗口 ←→ 主进程：`config:get`、`ui:config`、`config:set`、`ui:pauseShortcuts`、`ui:resumeShortcuts`

## 常见问题

- 快捷键显示不更新
  - 请执行 `yarn build:launcher`/`yarn build:dock` 后再 `yarn start`
  - 确保 `config.json` 键名与界面一致，保存后会主动刷新界面文案
- 视频播放按键被拦截
  - 开启“拦截按键”时仅拦截配置中的快捷键；若仍受影响，请关闭“拦截按键”
- 播放网页视频时播放器变黑
  - 在启动器顶部的“网页视频批注模式”选择“自动”并点击“重新检测浏览器”。检测到浏览器图形加速开启时，自动模式会选择“桌面镜像绘制”。
  - 若镜像模式下视频内容仍是黑色，通常是网站 DRM 或系统内容保护禁止屏幕采集；请改用浏览器画中画或关闭浏览器图形加速后选择“透明直绘”。
  - 模式切换会退出当前绘制；浏览器图形加速开关需要由用户在浏览器设置中修改并重启浏览器后，再回到本工具重新检测。
- 手写笔抖动时笔划提前结束或松笔后绘制点消失
  - 当前绘制层会锁定活动指针，过滤其他指针的 `pointerup`；手写笔收到短暂 `pointercancel` 时会等待恢复，不会立即结束笔划
  - 绘制模式使用自定义绘制点并隐藏系统光标；如果跨屏绘制，主进程会释放旧屏捕获并在目标屏重新捕获，降低事件落到网页或其他程序的概率
- 配置未生效或被覆盖
  - 确认 `config.json` 在程序路径（应用目录/安装目录）下；主进程仅在不存在时写入默认配置
- 启动后任务栏有图标但看不到界面
  - 新版本会自动把启动器窗口拉回当前可见显示器，并避免重复启动产生多个后台实例
  - 如果仍看不到窗口，请先在任务管理器结束所有 `Handwrite On Screen` 进程后重新启动
  - 启动异常日志位于 `%APPDATA%\handwrite-on-screen\logs\main.log`，也可在启动器底部点击“打开日志”直接定位。反馈问题时请一并提供该文件
  - 若完整启动器未完成渲染，窗口仍保留可操作的基础界面，可直接进入/退出绘制、打开日志或退出应用；8 秒后会自动显示故障页。日志会记录启动版本、页面资源加载失败、渲染进程退出和前端异常
  - 若日志中出现 `exitCode=-36861`，表示 Chromium 的 Crashpad 崩溃处理器未连接。本程序会在启动时启用本地 Crashpad，不上传崩溃数据；崩溃转储位于 `%APPDATA%\handwrite-on-screen\crash-dumps`，请连同 `main.log` 一并反馈
  - 默认使用软件渲染，避免网页硬件视频在透明手写层下显示黑屏。日志首行会显示 `rendering=software`
  - 若仍出现渲染进程退出，请提供 `main.log`、`chromium.log` 与 `%APPDATA%\handwrite-on-screen\crash-dumps` 中对应时间的转储文件
  - 防火墙通常不会影响启动器显示；它只可能影响云端学习等网络功能。显卡驱动、远程桌面或 Windows 桌面合成异常可能影响透明叠加层和视频显示，新版本启动器已改为非透明窗口以降低这类影响
- 颜色选择未生效
  - 叠加层支持 `#rgb`、`#rrggbb`、`rgb(...)`、`rgba(...)` 格式；若颜色仍未变化，请确认未处于橡皮擦工具
- 启动后粗细未匹配工具
  - 已支持按工具记忆粗细；请确认 `config.json.toolSizes` 中三种工具的值是否存在并正确

## 作者与联系方式

- 作者：newpc
- 邮箱：348246463@qq.com
- 仓库：https://gitee.com/newpc/handwrite-on-screen
- QQ 群：731235693