HandLayers

HandLayers

Overview

HandLayers is a free, open-source handwriting and drawing plugin for Markdown and PDF files. It is designed for desktop and iPad workflows, with a dedicated Apple Pencil input surface and layer-based annotation storage.

Features

• Write with Apple Pencil or a mouse while using touch to navigate the page.
• Annotate Markdown and PDF files without modifying their original contents.
• Organize ink, text, shapes, and temporary whiteboards in editable layers.
• Select, move, resize, rotate, copy, cut, paste, recolor, and export annotations.
• Export annotated PDFs or ZIP packages containing complete layer data.

Installation

Install HandLayers from the community plugin directory when the listing is available. For beta testing, install BRAT, run BRAT: Add a beta plugin for testing, and enter the GitHub repository ab11158/hand-note-layers.

Data and privacy

HandLayers stores annotation JSON files inside the local vault under .hand-note-layers. It does not send note contents, handwriting, or PDF data to an external service. Exported files are written to the vault's HandLayers 导出 directory.

Support and sponsorship

All features are free to download and use. Sponsorship is voluntary and does not unlock features or change access to updates and support. The project can be supported through the funding link shown in the plugin directory and manifest.

Release notes

0.10.5

• Resolved the blocking community-review checks without changing the Pencil writing pipeline.
• Added reproducible dependency metadata and English project documentation.
• Updated compatibility, command naming, and cleanup behavior recommended by the community plugin review tools.

中文说明

HandLayers 是一个 Obsidian 插件，用于在 Markdown 和 PDF 文件上添加基于笔记层的手写标注。

功能

• 在 Obsidian 原生文件中直接创建手写标注，不修改源文件。
• 支持 Markdown 文件。
• 支持 PDF 文件，包含翻页和缩放。
• 手指始终用于滚动页面，Apple Pencil 或鼠标用于书写。
• 手形浏览、钢笔、铅笔、荧光笔、套索选择、文本框和图形工具。
• 支持局部擦除与整笔擦除，连续擦除只占一步撤回。
• 工具栏保留4个颜色位，点击任一颜色位可从预置色板或拾色器重新设定，粗细数值实时显示；钢笔、铅笔和荧光笔最大粗细为48。
• 撤销、重做、清除当前层。
• 临时白板带8个缩放锚点，可移动、缩放并在内部滑动画布。
• 临时白板自动保存为草稿，关闭视图或重启后可以继续编辑。
• 临时白板可保存为最上方的 白板1、白板2 图层，白色背景和笔迹严格限制在白板方框内。
• 支持标准触控笔侧键/橡皮事件切换绘图工具与橡皮擦。
• 套索提供全选、矩形框选和自由套索三种模式。
• 多个笔记层默认按 图层1、图层2、图层3 递增命名，笔按钮指定唯一的当前编辑层；当前编辑层始终可见。
• 桌面端双击、iPad 长按图层名称可以重命名。
• 图层显示、隐藏、重命名、排序和 0% 到 100% 的整数透明度调整；滑条独占第二行，在 iPad 上保持完整可操作。
• 文本框统一使用固定在原文本位置的编辑框；输入实时回显到画布，选中文本后可用颜色槽改色并通过选区锚点缩放。图形支持直线/驻留折线、矩形、椭圆、圆、三点曲线和常见教学图形，并可组合实线、点线或虚线。
• 独立图片处理入口支持从 PDF 原始底图或临时白板可见区域生成派生图片。原始文件保持只读，处理结果和源图写入 .hand-note-layers/assets；支持 Lab 色差智能选区、连续/整图同色、增加/减少/反向/清除、扩大/收缩/平滑/羽化、背景换白和自定义填充、清理笔、受控除噪、裁剪、旋转、翻转、文字拉直与四角透视。
• 保存后的白板可通过图层笔按钮重新编辑；眼睛控制白底与笔迹整体显示或隐藏。只有点击普通图层的笔按钮切换编辑层时，正在编辑的白板才会保存当前修改并自动隐藏。
• 套索选区抬笔后按实际内容显示高对比度矩形、8 个缩放锚点和旋转柄，操作菜单立即出现。菜单中的“复制”会偏移约12px生成并选中副本，“拷贝”写入可跨笔记、页面和白板使用的插件剪贴板，“剪切”写入剪贴板并删除原对象；工具栏粘贴按钮或空白画布长按可把内容贴到当前可编辑图层。另支持删除、改色、截屏、锁定、编组、层级、对齐和分布。手指长按文本可直接选中，Pencil 在文本或套索工具下长按文本可选中。
• 荧光笔点按和极短笔画使用单次圆形渲染，避免半透明笔迹重复叠加成雪花状。
• PDF 工具栏下载按钮提供两种模式：合成原 PDF 与当前可见图层，或生成包含原文件、全部已保存图层独立 SVG、图层 JSON 和清单的 ZIP 图层包。未保存临时白板明确排除。
• 自动保存到 vault 中的 .hand-note-layers 目录。
• 工具栏显示保存状态，并支持立即保存。
• 支持桌面端和 iPad 移动端。

书写性能

• 0.5.9 使用独立实时笔迹 Canvas，并采用 MIT 许可的 perfect-freehand 生成压感轮廓；抬笔后才把当前笔合并到已完成笔迹层。
• 0.6.0 是 Apple Pencil 手势仲裁测试版：书写 Canvas 使用 touch-action: none，关闭注释滚动容器的 iOS 原生惯性滚动，手指仍使用插件内部平移；笔刷、图层、颜色和保存路径保持不变。
• 0.6.1 使用8槽位 Pencil 输入池：抬笔只封存原始笔画并立即释放活动状态，连续书写停顿150 ms后再批量生成最终轮廓、记录历史并发布文档；槽位占满时动态扩容，不拒绝第9笔。静止点笔保持单点坐标，避免后台平滑造成点位抖动。
• 0.6.2 强制按槽位1到8循环预备，并记录每笔的启动来源。正常笔标记为 real-pointerdown；如果真实Down缺失但出现带压力或接触按钮的Pencil move，则由当前预备槽位以 orphan-pointermove 救援启动。另行记录stylus Touch旁路信号，用于区分Down丢失、Pointer通道丢失和整段DOM数据缺失。
• 0.6.3 增加抬笔后350毫秒输入探针，同时监测 Pointer、pointerrawupdate、Stylus Touch 和兼容 Mouse 信号。该版本只扩展诊断，不改变书写、图层和保存热路径，用于确认漏笔数据是否曾到达 Obsidian WebView。
• 0.6.4 将现有透明Canvas改为Pencil专属输入终端：Pencil在窗口捕获阶段直接进入书写管线，不再使用Pointer Capture；Stylus Touch在Pointer缺失时接管完整笔画，并拦截书写区域内由短笔产生的兼容点击。手指继续只负责页面平移。
• 0.6.5 修复临时白板整体移动和缩放锚点被Pencil书写层抢占的问题。白板控制按钮会独立捕获拖动指针，移动期间保持外框与内部画布稳定，手指和Pencil均可操作控制柄。
• 0.6.6 将Pencil的坐标救援严格限制在当前Hand Note Layers视图内，避免后台注释Canvas误拦截Obsidian设置页、第三方插件列表及其他工作区界面的点击。
• 0.7.0 固化“编辑层必定可见”和白板锁定规则，修复透明度滑条拖动时被面板重建打断的问题；移除8槽位、输入探针及诊断旁路，只保留已验证的Pencil专属输入层，并加入当前文件与全仓库导出包。
• 0.8.0 恢复已保存白板的再次编辑，按普通图层笔按钮时自动收起并隐藏当前白板；透明度使用0到100整数滑条，套索增加移动、8锚点缩放与长按菜单，修复荧光笔点按雪花，并在PDF工具栏加入真正的带批注PDF导出。
• 0.9.0 将透明度滑条改为独立整行并支持从0%恢复编辑；新增文本框、带锚点的直线/矩形/椭圆/光滑曲线，笔触上限提高到48，并为PDF下载按钮增加合成PDF与全图层ZIP两种导出模式。
• 0.9.1 强化固定文本输入面板并在完成后自动选中文本；套索按实际内容显示高对比度边框、8 个缩放锚点和旋转柄，新增复制、拷贝、剪切、粘贴、删除、改色与选区截屏，并修复滚动或白板平移后的选框坐标。
• 0.10.0 增加跨笔记插件剪贴板、工具栏与空白长按粘贴、图形本体拖动和编组操作；直线支持约420毫秒驻留折线与闭合锚点，新增线型、端点、填充、三类连接器、边缘吸附和路径控制点，并同步到 SVG、PDF 与选区截屏。Pencil 自由书写继续使用原有单一实时输入管线。
• 0.10.1 精简文本和套索对象菜单，恢复原位文本输入，并修复工具栏二级菜单和导出入口。
• 0.10.2 将插件显示名改为 HandLayers，精简图形菜单，增加常见教学图形和四种命令面板导出方式。
• 0.10.3 修复圆、椭圆和常见图形拖动起点漂移；折线驻留增加抗抖候选锚点，曲线改为经过三点确定；工具栏与选区菜单防溢出，并统一为 50% 半透明背景。
• 0.10.4 使用标准贝塞尔圆弧系数平滑圆与椭圆，并统一画布、SVG、PDF 和截屏导出的几何效果；同时增加爱发电自愿赞助入口并修正开源许可证署名。
• 0.11.0 新增非破坏式图片处理系统：PDF 与临时白板区域生成“白色遮挡 + 派生图片”，提供传统颜色选区、背景填充、局部清理、受控除噪和几何校正，并让合并 PDF、当前图层 ZIP 与整库导出携带派生图片资源。图片计算与 Pencil 实时书写管线隔离。
• 0.11.1 简化图片处理入口：PDF 仅由 Pencil 框选，Markdown 内嵌图片由 Pencil 直接点选；手指统一用于页面滚动，图片处理自动采用周围页面背景色，并精简压缩工具栏与颜色槽交互。
• 0.11.2 新增图片选区方式按钮：单击恢复上次的框选或自由套索，双击选择全选、框选或自由套索；增加/减少选区可与几何选区组合，并提供自动、白色、透明和自定义遮挡色。
• 0.10.5 修复社区插件自动审核阻断项，补充英文文档与可复现依赖配置；Apple Pencil 单一实时书写管线保持不变。
• Pencil 同一帧的合并采样会批量绘制，避免逐采样点重复提交 Canvas。
• Pencil 使用单一实时输入管线；即使上一笔状态异常，新落笔也会立即接管并完成上一笔，不阻塞连续书写。
• Pencil 与手指平移共用稳定的指针捕获机制，同时保留新落笔接管保护，减少 iPad WebView 丢失笔画事件的概率。
• 落笔使用滚动和尺寸更新时缓存的 Canvas 几何信息，不再为每一笔强制读取页面布局。
• 0.5.5 兼容测试管线将 Pencil 归一化为固定压力的普通接触点，只读取主事件坐标并立即增量绘制，不使用合并采样或触控笔快捷数据。
• 0.5.6 诊断版保持相同书写行为，并记录 Pencil 在窗口、文档和 Canvas 捕获阶段的到达时间、事件排队延迟、首个移动事件、指针捕获状态、绘制后两帧时间及主线程长任务。
• 笔画结束后的文档发布与自动保存延后执行，颜色、图层和保存逻辑不进入书写热路径。
• 新笔画使用轻量撤销记录，笔画较多时不再为每次落笔复制完整图层笔画数组。
• Markdown 的局部工作画布维持当前可视区域及边距，降低 iPad 上的大画布内存压力。

在 iPad 上安装

1. 在 Obsidian 设置中关闭安全模式或受限模式。
2. 安装社区插件 BRAT。
3. 启用 BRAT。
4. 执行命令 BRAT: Add a beta plugin for testing。
5. 输入本插件的 GitHub 仓库地址。
6. 安装完成后启用 HandLayers。

使用

打开一个 Markdown 或 PDF 文件，然后：

• 点击左侧 Ribbon 中的 pen-tool 图标。
• 或执行命令 标注当前文件。

Markdown 文件会进入独立的标注视图。PDF 文件默认会使用 HandLayers 的 PDF 标注视图打开。

Apple Pencil 2 的笔背双击属于 iOS 原生 UIPencilInteraction。Obsidian 社区插件目前无法直接读取该原生回调；插件已支持 Web Pointer Events 能够提供的触控笔侧键/橡皮事件，并提供 切换绘图工具与橡皮擦 命令。

支持项目

HandLayers 免费开源，全部正式功能均可免费下载和使用。赞助完全自愿， 不会解锁额外功能，也不会影响插件安装、更新、问题反馈或功能使用。

如本插件对你有帮助，可以通过爱发电支持持续开发、iPad 兼容测试、 问题修复、文档维护和版本发布：

https://afdian.com/a/ab11158

导出

命令面板提供：

• 导出当前 PDF（合并可见批注）
• 导出当前笔记所有图层 ZIP
• 导出整个仓库的批注 PDF
• 导出整个仓库的所有图层 ZIP

导出结果保存在仓库的 HandLayers 导出 目录，包含源文件副本、 完整图层数据和合并后的可见图层 SVG。未保存的临时白板不会进入导出， 完成提示会显示被排除的数量。

PDF 标注视图工具栏中的下载按钮提供“合并 PDF”和“所有图层 ZIP”。 合并 PDF 只合并当前可见图层并保留原 PDF 页面；ZIP 包含原文件、全部 已保存图层的独立 SVG、完整图层 JSON 和导出清单。

套索菜单中的“截屏选区”导出当前可见范围内的 PNG。PDF 会包含页面底图和 可见标注，临时白板会包含白色底图和可见标注；Markdown 当前只导出可见 标注层，不栅格化 Markdown 正文。

数据存储

每个源文件对应一个标注 JSON 文件，保存位置：

.hand-note-layers/源文件路径.json

标注文件不会修改原始 Markdown 或 PDF 内容。

本地开发

npm install
npm run dev

生产构建：

npm run build

构建后确认仓库根目录包含：

main.js
manifest.json
styles.css

GitHub Release

创建并推送 Git tag 后，GitHub Actions 会自动构建并发布 Release。

git tag 0.5.6
git push origin 0.5.6