# Ink Whiteboard 墨迹白板 · 插件介绍与详细使用手册

> 版本：1.0.3
> 更新：2026-08-20
> 适配：Obsidian 1.5.0 及以上
> 平台：桌面端 / 移动端
> 授权：Ink Whiteboard Pro 商业授权（需激活）
> 更新日志：[CHANGELOG.md](CHANGELOG.md)

---

## 一、插件介绍

### 1.1 这是什么

Ink Whiteboard 是一款面向 Obsidian 的**独立无限白板**插件。它把以下能力整合进同一套可缩放的工作台：

- 手写墨迹（钢笔 / 荧光笔 / 橡皮，压力感应）
- 多源节点（卡片、文本框、表格、图片、文件、Markdown、PDF、网页、音视频）
- 数据可视化（Base / Dataview / 多维表嵌入、实时数据组件与首页组件）
- 结构化图（思维导图、流程图、研究框架、Mermaid、神经网络架构图）
- 关系连线（端点连接，保存为 `relations` 索引）
- 手账版面（贴纸、胶带、照片墙、周计划、Year in Pixels 等）
- 演示路线（把选区或当前视口编排为镜头，支持播放与自由漫游）

它不依赖 Obsidian 自带的 Canvas，使用独立的 `.iwb / .iwm / .iwd` 文件格式，自带渲染引擎、命令面板和导出能力。

### 1.2 适合谁、适合做什么

- **学习 / 研究**：课堂与读书手写批注、把 PDF/笔记/图片整理成可连接的知识地图、技术路线图、人物关系图。
- **项目 / 效率**：用任务看板、进度、统计图、热力图跟踪项目；SWOT / OKR / BMC / 风险矩阵等框架模板。
- **创作 / 手账**：照片墙、周计划跨页、旅行手账、习惯打卡版面。
- **绘图 / 表达**：流程图、泳道图、架构图，导出为 PNG/SVG/JPG/PDF。

### 1.3 与 Obsidian 的联动

- 可从文件列表或系统文件管理器**拖入** `.md` / `.pdf` / 图片 / 媒体文件。
- 库内资源直接预览并保留来源引用；外部图片复制进附件目录。
- 数据组件实时读取 Vault / Dataview / Base / Daily Notes，并随库内变化自动刷新。
- Markdown 笔记可用 `![[白板.iwb]]`、`![[导图.iwm]]` 或 `![[绘图.iwd]]` 嵌入真实白板预览。
- 支持把当前 Obsidian Canvas 转为 Ink 白板，也可从 OPML 导入思维导图。
- 库内文件或文件夹重命名后，白板中的来源路径、双链和嵌入引用会自动迁移。

---

## 二、安装、激活与更新

1. 将插件文件夹放入当前库的 `.obsidian/plugins/ink-whiteboard/`。
2. 确认文件夹内包含 `manifest.json`、`main.js`、`styles.css`。
3. 在 Obsidian「设置 → 第三方插件」中启用 **Ink Whiteboard Pro**。
4. 打开插件设置，输入 `IWB1` 开头的购买码完成本机激活。未激活时只显示激活、恢复、设备管理、同步和检查更新入口，不会修改已有白板文件。
5. 点击左侧 Ribbon 的「打开白板工作台」，或在命令面板搜索相关命令。

授权与更新相关命令：

- 激活 Ink Whiteboard Pro
- 使用恢复码恢复白板授权
- 管理白板授权设备
- 同步白板授权状态
- 检查 Ink Whiteboard Pro 更新

插件启动和后台运行只做本地授权验证。只有主动执行激活、恢复、设备管理、同步或检查更新时才会联网；不会上传 Vault、文件名、白板内容或使用数据。桌面端授权数据由系统安全存储保护，移动端保存在独立 IndexedDB 中，不写入 Vault。

---

## 三、文件与工作空间

| 类型 | 扩展名 | 用途 |
|---|---|---|
| 自由画布 | `.iwb` | 手写、卡片、文本框、文件、表格、数据组件、框架/手账模板。 |
| 思维导图 | `.iwm` | 结构化主题、分支、折叠、标记、布局整理。 |
| 绘图 | `.iwd` | 流程图、架构图、泳道、图形库、连接线、对齐吸附。 |

**全局命令**（命令面板，`Ctrl/Cmd + P`）：

- 打开白板工作台
- 新建自由画布 / 新建思维导图 / 新建绘图
- 当前 Markdown 转思维导图 / 转 SWOT 分析 / 转 OKR 目标树
- 当前 Obsidian Canvas 转 Ink 白板
- 从 OPML 导入思维导图
- 生成 CNN 架构图（VGG-16）/ 生成 Transformer 架构图
- 激活 / 恢复 / 管理设备 / 同步授权 / 检查更新

> `.iwb`、`.iwm`、`.iwd` 是彼此独立的专用文件，不会在当前文件里暗建其他类型的隐藏空间。跨文件复用节点请使用 `Ctrl/Cmd+C`、切换目标文件后 `Ctrl/Cmd+V`。在 `.iwb` 中执行「组织为脑图」会新建 `.iwm` 文件并保留原节点。

---

## 四、界面与导航

| 操作 | 方式 |
|---|---|
| 平移 | 滚轮滚动 / 触控板双指 / 按住空格拖动 |
| 缩放 | `Ctrl/Cmd + 滚轮` 或右下角缩放控件 |
| 适配全部内容 | `Ctrl/Cmd + 1` |
| 适配选中对象 | `Ctrl/Cmd + 2` |
| 重置到 100% | `Ctrl/Cmd + 0` |
| 白板内部命令面板 | `Ctrl/Cmd + K` |
| 小地图定位 | 右下角缩略图，可拖动视口 |

> 鼠标位于表格、Base、数据组件等可滚动内容上时，滚轮优先滚动该组件而非画布。

> PC 与移动端使用独立的平台策略。触摸屏 Windows 电脑仍使用桌面渲染路径；缩放、触控板平移、键盘移动和拖动期间，卡片、表格与数据组件会保持可见，不会为了性能而卸载整层内容。

---

## 五、画布工具

| 工具 | 快捷键 | 说明 |
|---|---|---|
| 选择 | `V` | 选择、移动、缩放、复制、编组、对齐、设样式。 |
| 钢笔 | `P` | 压力感应笔宽书写或勾画。 |
| 荧光笔 | `H` | 半透明高亮标注。 |
| 橡皮 | `E` | 擦除笔迹。 |
| 连接线 | `C` | 从节点端点创建关系连线。 |

钢笔 / 荧光笔 / 橡皮提供快捷预设（黑色细笔、蓝色批注、红色批改、黄/绿荧光、整笔橡皮等）。进入墨迹工具后，浮动面板可调节颜色、粗细、透明度、橡皮参数。

选中笔迹后，「更多」菜单可：套用当前笔刷样式、复制/粘贴/复制一份、调整粗细与透明度、调整层级、收纳为墨迹片段。

---

## 六、插入内容

自由画布「插入」菜单包含：

- **基础**：卡片、文本框、表格。
- **媒体/数据**：图片卡片、图片贴图、文件、网页 / iframe、Base 数据库、数据嵌入、Mermaid 图表；拖入音视频文件可生成对应媒体节点。
- **图形**：矩形、圆形、菱形、箭头。
- **数据组件**：任务进度、任务看板、统计图、活跃热力图、习惯打卡、最近笔记。
- **手账贴纸**：便签、TODO 标签、Memo 标签、胶带、纸夹、爱心、星标、闪光、叶子、花朵、日历卡片。
- **框架模板**：看板、SWOT、艾森豪威尔矩阵、风险矩阵、BMC、Lean Canvas、OKR、用户故事地图、人物关系图。
- **手账模板**：照片墙、周计划、习惯打卡、Year in Pixels、旅行路线、旅行时间轴。

也可直接把文件拖入画布（`.md` / `.pdf` / 图片 / 常见媒体）。外部图片复制进附件目录，库内文件保留来源引用。

---

## 七、卡片与文本框

### 7.1 卡片（内容优先）

卡片采用**内容优先**设计：放置后直接写正文，**标题可选**。

- 标题留空时，标题栏显示「添加标题」占位提示，点击即可补标题，不会强塞默认标题。
- 正文识别 Markdown 语法（标题、列表、待办、表格、双链、代码、强调等）并渲染预览。
- 双击卡片进入编辑；正文支持局部富文本（见 7.3）。

### 7.2 文本框（Visio 式）

文本框是**纯文字块**，没有标题栏 —— 正文首行即标题，像 Visio 的「文本框」那样只显示文字本身。

- **绘制**：选「文本框」后在画布**拖拽**画出尺寸，或**单击**用默认大小落一个。
- 双击进入编辑，支持富文本排版。

### 7.3 正文富文本

卡片 / 手账正文在编辑选中文字时会弹出排版工具条，支持：

- **加粗 / 斜体 / 下划线**
- **字号**调整（增大 / 减小）
- **文字颜色**与**高亮**

> 富文本以叠加层（textRuns）方式保存在正文之上，纯文本仍是真实来源。

---

## 八、节点操作与快捷键

- 单击选中、拖动移动、拖边角缩放。
- 双击编辑文本/卡片/表格/Mermaid/Markdown 等可编辑内容。
- 右键节点：连接、复制/剪切/删除、打开来源、转换 Mermaid、释放墨迹片段、复制到其他空间。
- 多选后：编组/解组、批量样式、对齐分布、层级调整。

| 操作 | 快捷键 |
|---|---|
| 全选 | `Ctrl/Cmd + A` |
| 复制 / 剪切 / 粘贴 | `Ctrl/Cmd + C/X/V` |
| 复制一份 | `Ctrl/Cmd + D` |
| 删除 | `Delete` / `Backspace` |
| 编辑当前对象 | `F2` |
| 编组 / 解组 | `Ctrl/Cmd + G` / `Ctrl/Cmd + Shift + G` |
| 上移 / 下移层级 | `Ctrl/Cmd + ]` / `Ctrl/Cmd + [` |
| 置顶 / 置底 | `Ctrl/Cmd + Shift + ]` / `Ctrl/Cmd + Shift + [` |
| 锁定图形 | `Ctrl/Cmd + Shift + L` |

---

## 九、连线与关系

每个节点四边都有端点，创建连线两种方式：

1. 选「连接线」工具，点起点端点 → 再点目标端点。
2. 选择工具下从端点拖拽到另一节点端点。

连线支持：编辑标签、反转方向、单向/双向/无向关系、实线/虚线、连接路线与端点锚点、复制粘贴连线样式。按 `Esc` 取消当前连接。

> 保存白板时按端点关系生成 `relations` 索引，便于检索、知识图谱或后续 AI 扩展。

---

## 十、表格

电子表格式交互。

**选择与编辑**
- 单击选中单元格；双击 / `Enter` / `F2` / 直接输入进入编辑。
- 编辑中 `Enter` 提交并下移；`Esc` 提交退出；`Shift+Enter` 换行。
- 方向键移动选择；`Delete`/`Backspace` 清空选中。
- 拖拽选区，右下角填充手柄扩展选区。

**行列与结构**
- 悬停显示行列把手；点把手选整行/整列；拖把手重排。
- 行列边界加号插入行/列；拖边界调整行高/列宽。
- 右键：插入/删除/选择行列，合并/取消合并单元格。

**格式与内容**
- 工具条：字体、字号、粗体、斜体、下划线、对齐、单元格底色、文字颜色、清空格式。
- 单元格支持：待办复选框、单元格配图、Markdown 渲染、嵌套表格、区域复制粘贴、与外部表格 Tab 分隔互通。

---

## 十一、Markdown、文件、图片、PDF、网页与音视频

- **Markdown**：拖入 `.md` 用 Obsidian 渲染预览，保留来源路径，可「打开来源」。命令面板支持「转思维导图 / 转 SWOT / 转 OKR」，读取标题或缩进列表结构生成新白板文件。
- **图片与文件**：图片可作「图片卡片」或「图片贴图」；库内图片直接引用，外部图片复制进附件目录；普通文件节点显示文件信息并可打开来源。
- **PDF 与批注卡片**：PDF 作为资料源卡片放入；PDF 批注卡片显示来源文件、页码、摘录与跳回入口，含手写批注的卡片显示批注标记。
- **网页 / iframe**：插入菜单选择「网页 / iframe」，粘贴 `http(s)` 地址或 iframe 代码。部分网站会通过自身安全策略拒绝嵌入；白板不会授予网页剪贴板读取或沙箱逃逸权限。
- **音视频**：把库内音频、视频拖入白板即可创建媒体节点；视频帧、来源路径和相关笔记可继续作为白板资料组织。
- **白板嵌入笔记**：在 Markdown 中写 `![[项目白板.iwb]]`、`![[知识导图.iwm]]` 或 `![[流程图.iwd]]`，阅读视图和实时预览会显示白板缩略画面。默认保持静态以免抢占笔记手势，点击打开原白板。
- **格式转换**：当前 `.canvas` 文件可通过命令或文件右键菜单转为 Ink 白板；OPML 文件可从命令面板或文件右键菜单导入为思维导图。

---

## 十二、Base 与数据组件

### 12.1 Base 数据库节点

插入「Base 数据库」后选择 `.base` 文件路径，白板读取其视图、字段顺序、筛选与数量限制，渲染为表格/卡片/列表，结果文件可点击打开。

支持的筛选表达式：`file.hasTag("#tag")`、`file.inFolder("folder")`、`field == "value"`、`field != "value"`。

### 12.2 数据组件总览

核心工作组件中，除习惯打卡外都可选 **Vault 元数据 / Obsidian Base / Dataview 查询** 三种数据来源；另外提供最近笔记与首页仪表盘组件。

| 组件 | 默认尺寸 | 作用 |
|---|---|---|
| 任务进度 | 460×220 | 完成数 / 总数 / 完成百分比环 |
| 任务看板 | 620×360 | 待办/进行中/已完成 三列拖拽 |
| 统计图 | 620×360 | 柱/饼/折线，6 种分组维度 |
| 活跃热力图 | 620×300 | GitHub 风格近一年活跃日历 |
| 习惯打卡 | 760×480 | Daily Note 联动的打卡日历 |
| 最近笔记 | 自动 | 最近修改的笔记列表，点击即可打开 |

**添加**：插入菜单 →「数据组件」，或命令面板 `widget-progress / widget-kanban / widget-chart / widget-heatmap / widget-habit`。

**配置**：组件标题栏右上角 **齿轮 ⚙**，或右侧面板「配置组件」。弹窗分「基础 / 数据来源 / 字段与数量」三段，字段随组件类型动态显隐；表单较长时正文区滚动、底部「保存/取消」常驻可见。

### 12.3 各组件要点

**任务进度** — 优先按正文 `- [ ]` 任务行比例算进度；无任务行则按 frontmatter `status` 判断（识别 done/完成/已完成/completed/x/true）。

**任务看板** — 两种模式：
- *文档待办*：卡片来自正文 `- [ ]`，按勾选符分列（`[ ]`待办、`[/]`/`[>]`进行中、`[x]`已完成）。拖卡改勾选符、点复选框一键完成、双击文字内联编辑、`+ 添加待办`写入扫描文件夹下的 `待办收集箱.md`，自动识别 Tasks/Dataview/ISO 日期并标「今天/逾期」。写回前会校验原始任务行；如果笔记已被外部编辑导致行位置变化，会拒绝覆盖并提示刷新重试，同时保留原文件换行格式。
- *笔记状态*：一篇笔记一张卡，按 frontmatter `status` 分列，拖卡写回该字段。

**统计图** — 维度：按状态/标签/属性/文件夹（柱或饼）、创建趋势/修改趋势（强制折线，按月分桶）。可选数值字段加权，否则每条记 1；分类维度最多 12 项按值降序。

**活跃热力图** — 按日期字段（默认 `date`）分桶近 ~370 天；色阶 5 级，可用数值字段加权；点格子打开当天笔记。配置项含扫描文件夹、日期字段、数值字段、扫描上限（默认 2000，最高 10000）。

**习惯打卡** — 数据源固定 Daily Note。读取当天日记 `## 习惯打卡` 区的 `- [x] 习惯名`；今日行点击一键打卡并写回日记（日记不存在自动创建）；周/月/年切换日历跨度。配置「习惯列表（逗号分隔，最多 12）」「统计范围」。

**首页组件** — 首页/个人主页模板还可使用欢迎横幅、倒计时、快捷入口、库统计、那年今日和每日一言。它们分别用于显示时间与库龄、目标日期、常用笔记/文件夹/白板、Vault 概览和内容回顾。

**数据嵌入** — 插入菜单选择「数据嵌入」，可粘贴 `![[...duowei]]`、`![[...base]]` 或带图表参数的块引用，把已有多维表、Base 或图表作为独立组件放到白板。

### 12.4 数据准备模板

```yaml
---
status: doing        # 进度 / 看板(笔记模式) / 统计(按状态)
date: 2026-06-20     # 热力图 / 看板日期
count: 3             # 热力图强度 / 统计数值字段(加权)
priority: 高          # 统计「按属性」
tags: [项目, 健康]    # 统计「按标签」
---

- [ ] 待办任务        # 进度计数 / 看板「文档待办」
- [x] 已完成任务

## 习惯打卡            # 习惯组件写回区(可手改)
- [x] 阅读
- [ ] 运动
```

> 组件监听库内 Markdown / Base 变化并 debounce 自动刷新。移动端降低查询并发，优先刷新当前选中组件。

---

## 十三、Mermaid 与架构图

- 插入「Mermaid 图表」后输入语法并预览；常见 `flowchart`/`graph` 可经节点工具或右键**转换为可编辑流程图节点与连线**。
- 命令面板「生成 CNN 架构图（VGG-16）」「生成 Transformer 架构图」会创建新绘图文件，内部节点可继续编辑、移动、连线、改样式、导出。

---

## 十四、思维导图

三种布局：辐射状 / 右侧 / 树形。

| 操作 | 快捷键 |
|---|---|
| 添加子主题 | `Tab` 或 `Insert` |
| 添加同级主题 | `Enter` |
| 整理当前导图 | `Ctrl/Cmd + Shift + R` |
| 调整同级顺序 | `Alt + ↑/↓` |
| 提升 / 降低层级 | `Alt + ←/→` 或 `Shift + Tab` |

右键/工具栏：折叠/展开分支、选择分支、选择整张导图、复制分支、复制一份、设置主题标记。自由画布普通节点可右键「设为导图中心」或「接入当前导图」。

从 Markdown 生成思维导图时会自动绑定源笔记，之后笔记大纲与导图结构可双向同步。也可以导入幕布、MindNode、WorkFlowy 等工具导出的 OPML 大纲。

---

## 十五、绘图与模板

绘图空间适合流程图、架构图、技术路线图：

- 图形库：流程图形、文档、数据、数据库、引用、气泡、泳道、神经网络组件等。
- 模板：基础流程图、跨部门审批泳道、内部结算泳道、TCP 状态循环、研究框架图。
- 连接线自动吸附端点；网格吸附 + 对象对齐吸附。
- 多选对齐：左/中/右、顶/底对齐，水平/垂直分布。
- 层级调整与锁定（`Ctrl/Cmd + Shift + L`），图形/连线样式、箭头、虚线、标签编辑。

---

## 十六、演示路线

顶部标题栏选择「演示」：

1. 先选中节点、笔迹或连线，选择「将选区添加为镜头」；也可以把当前视口直接添加为镜头。
2. 打开「编辑演示路线」预览、删除或拖动调整镜头顺序。
3. 选择「从头演示」或「从当前镜头演示」。播放中用 `→` / `PageDown` / `Space` 下一镜头，`←` / `PageUp` 上一镜头，`Home` / `End` 跳到首尾，`R` 进入自由漫游，`Esc` 退出。
4. 自由漫游时可照常缩放和平移；按 `R` 返回演示路线，`Alt+←` 返回上一个镜头位置。

演示路线与白板一起保存，移动节点后镜头仍会根据关联对象重新定位；被删除的镜头内容会在编排面板中标记为失效。

---

## 十七、导出与保存

白板自动保存；也可在「更多」菜单或内部命令面板执行「保存白板」。

- 内容修改会延迟合并并串行写入，避免多个保存互相覆盖。
- 正常写入会保留最近的 JSON 恢复备份；读取损坏文件时优先尝试备份，并阻止恢复模式覆盖原文件。
- 关闭白板时若保存失败，会立即重试；再次失败会在白板目录的 `Recovery` 子目录创建可直接打开的恢复白板。
- 移动端切到后台前会立即提交待保存内容；若原路径不可写，同样尝试创建恢复副本。

导出（「更多 → 导出图片…」或内部命令同名项）：

- **范围**：选区 / 当前视口 / 全部内容
- **格式**：PNG / SVG / JPG / PDF
- **背景**：白色 / 透明
- **PDF 页面**：自动 / A4 / A3 / Letter
- **目标**：保存到库内 / 复制到剪贴板

---

## 十八、移动端说明

支持移动端。为降低内存压力，会对大图、PDF、Markdown 渲染缓存、数据组件查询、超大墨迹画布做轻量化；切后台先保存再释放图形内存，回前台恢复视图。

移动端与 PC 的行为按 Obsidian 原生平台区分，而不是仅凭是否存在触摸屏。卡片和组件在双指缩放、平移与拖动期间保持可见；高性能平板保留较高渲染质量，手机和低内存设备使用更保守的缓存预算。

建议：单张白板避免同时打开过多大型 PDF/高清图；数据组件设置数量上限；大型白板按空间拆分（画布/导图/绘图分开）。

---

## 十九、常见问题

- **拖入的外部图片在哪？** 复制进库内附件目录，节点引用复制后的库内路径。
- **数据组件/查询表没结果？** 确认数据源存在；Dataview 源需启用 Dataview 插件；Base 源需正确的 `.base` 路径与视图名。
- **热力图记录变少？** 依次查：扫描文件夹路径是否正确、日期字段名是否与 frontmatter 完全一致、日期是否为 `YYYY-MM-DD` 可解析格式、扫描上限是否太小、是否超出近 ~370 天窗口。
- **表格复制不全？** 先单击选中单元格/区域再复制；编辑态复制的是输入框内选中文本。
- **连线连不上？** 从节点边缘端点起拖，或用连接线工具点起点与目标端点；`Esc` 取消。
- **导图加不了分支？** 先选中一个导图主题再 `Tab`；普通节点需先「设为导图中心」或「接入当前导图」。
- **导出没有透明背景？** 导出弹窗背景设为透明，并选 PNG 或 SVG。
- **移动、缩放时卡片先消失再出现？** 先确认插件设置/第三方插件列表中版本为 `1.0.3` 或更高，并重新加载插件。当前版本不会在视口交互期间隐藏富节点层；若仍出现，请同时记录设备平台、操作方式和白板节点类型。
- **看板任务提示“内容已变化”？** 源笔记在组件刷新后又被编辑，白板为避免改错任务已拒绝覆盖。等待组件刷新或重新打开白板后再操作。
- **关闭时提示创建恢复白板？** 原文件当时不可写或保存连续失败。按提示路径打开 `Recovery` 中的副本，确认内容后再决定是否替换原文件。
- **网页节点空白？** 目标网站可能设置了 `X-Frame-Options` 或 CSP，禁止被第三方 iframe 嵌入；请改用普通文件/链接卡片在浏览器中打开。

---

## 二十、授权、隐私与文件安全

Ink Whiteboard Pro 是商业授权软件，不使用 MIT 许可。默认买断授权支持 3 台设备并包含永久更新权益；实际权益以购买凭证和许可证信息为准。

- 白板内容始终保存在用户自己的 Vault 中，停用或授权失效不会删除、改写白板文件。
- 授权失效时插件只关闭自身白板视图并隐藏 Pro 功能，普通 Obsidian 标签页不受影响。
- 激活、恢复、设备管理、主动同步和检查更新只在用户操作后联网，不上传笔记或白板内容。
- 主动更新会验证产品身份、发布签名、文件白名单、大小和 SHA-256；安装失败会自动回滚，并只保留最近 3 份本地回滚备份。