QOwnNotes 笔记关系(Note Relations)面板深度指南:链接语法、图布局与后台收集机制
QOwnNotes 笔记关系(Note Relations)面板深度指南:链接语法、图布局与后台收集机制
导读
笔记关系(Note Relations)面板是 QOwnNotes 中用于可视化当前笔记与其他笔记之间关联关系的图形化工具:它以当前笔记为中心,将笔记渲染为可拖动的节点,把“链接到另一篇笔记”的关系渲染为连线,并以同心圆布局逐层展开多级关联。本文将以仓库文档 webpage/src/getting-started/note-relations.md 为主线,结合 noterelationscene.cpp、note.cpp 等源码,完整讲解笔记链接的创建方式与语法规则、面板的开启与交互操作,以及其背后的图布局算法和后台线程收集机制。读完本文,你将掌握如何用 Note link 对话框建立笔记关联、如何手动书写可被识别的笔记链接、如何熟练操作关系面板,并理解该功能的实现原理。
什么是笔记关系面板
笔记关系面板用于展示当前笔记与它所链接笔记之间的关系,并且可以逐层(多个层级深度)展开。面板中:
- 中心节点是当前笔记;
- 周围的节点是当前笔记通过链接引用的其他笔记;
- 节点之间的连线表示“存在链接关系”;
- 每个节点还会继续展开它所链接的下一层笔记,形成多级关系图。
功能入口与基本交互:
- 通过菜单 Window / Panels(窗口 / 面板)开启面板;
- 支持用鼠标滚轮缩放关系图;
- 双击任意笔记节点即可在编辑器中打开该笔记;
- 节点本身可以拖动,连线会随节点位置实时更新。
面板的实现对应源码中的 NoteRelationScene 类(noterelationscene.h),它在主窗口中以一个名为 Note relations 的 Dock 面板(mainwindow.cpp)形式存在,默认隐藏,需要用户在菜单中手动打开。
建立笔记关系:从 Note link 对话框说起
原文档指出,笔记之间的关系可以通过链接到另一篇笔记来建立,例如使用 Note link(插入笔记链接)对话框。
对话框的调用入口
在编辑器中将光标放在目标位置(或先选中一段文字作为链接标题),然后触发“插入笔记链接”动作。该动作在源码中的槽函数为 on_actionInsert_note_link_triggered()(mainwindow.cpp),它调用 handleTextNoteLinking(LinkDialog::NoteLinkPage),最终弹出 LinkDialog(linkdialog.cpp)。
LinkDialog 的笔记列表页会列出当前笔记库中的所有笔记,每一行显示:
- 笔记名称;
- 所在子文件夹路径(当开启子文件夹显示时);
- 关联标签;
- 最后修改时间。
列表默认按修改时间降序排序,并支持在搜索框中按名称过滤(输入至少 2 个字符后才会触发搜索,见 linkdialog.cpp)。
对话框如何生成链接文本
确认选择后,主窗口根据情况生成不同的链接文本(mainwindow.cpp):
- 若用户填入了 URL,则生成普通 Markdown 链接
链接名,或仅填入 URL 时生成尖括号形式<url>; - 若开启了 Wiki 链接支持并勾选了 wiki 复选框,则生成 wiki 风格链接
[[笔记名]]; - 否则生成指向笔记的 Markdown 链接,格式为
笔记名,若同时选中了目标笔记的某个标题,还会在链接目标末尾追加#标题(标题会经过百分号编码,见 mainwindow.cpp)。
此外,链接名称中不允许出现 ] 字符,因为会破坏 Markdown 链接语法,对话框为此专门设置了输入校验器(linkdialog.cpp)。
笔记链接的语法规则
原文档给出了笔记链接的示例语法:My note。实际运行时,Note::findLinkedNotes()(note.cpp)会扫描笔记全文,识别以下多种形式的链接作为“关系”:
| 链接形式 | 说明 |
|---|---|
My note |
标准 Markdown 链接,目标为相对文件路径(空格需百分号编码为 %20) |
<path/to/My%20note.md> |
尖括号包裹的相对路径 |
My note |
带片段(锚点)的 Markdown 链接,# 之后指向笔记内的标题 |
<note://笔记名> |
传统 note:// 协议链接 |
My note |
以 note:// 协议为目标的 Markdown 链接 |
[[笔记名]] |
Wiki 风格链接(需在设置中开启 Wiki 链接支持) |
[[笔记名#标题|别名]] |
带锚点与别名的 Wiki 链接 |
值得注意的细节:
- 源码同时搜索“URL 编码过”和“未编码”两种相对路径,以兼容旧版本对斜杠的编码差异(note.cpp);
note://链接还支持“下划线替换为连字符”的模糊匹配,例如<note://Link-test2>可以命中名为Link test2的笔记(note.cpp);- Wiki 链接需要设置项
Editor/wikiLinkSupport开启后才生效(note.cpp),该设置可在“编辑器”设置中切换。
单元测试 testWikiLinksShowInNoteRelations(test_notes.cpp)验证了 [[目标]] 与 [[目标#标题|别名]] 两种形式都会被 findLinkedNotes() 正确收集,并归并到同一目标笔记上。
开启面板与操作方式
开启与隐藏
在菜单 Window / Panels 中找到“笔记关系”面板项并勾选,即可显示关系图。布局管理器会在重置布局时将该面板恢复为隐藏状态(layoutmanager.cpp)。
缩放、拖动与打开笔记
关系图使用 ZoomableGraphicsView 呈现(noterelationscene.h),其行为包括:
- 鼠标滚轮缩放:向上滚动放大、向下滚动缩小,缩放系数为
1.15,并且以鼠标指针位置为缩放锚点(AnchorUnderMouse),便于聚焦查看局部关系(noterelationscene.cpp); - 拖动平移:视图启用了
ScrollHandDrag拖拽模式; - 拖动节点:每个
NoteItem节点都可移动(ItemIsMovable),移动时连线自动跟随(ConnectionLine::updatePosition()实时重算两端中心点,见 noterelationscene.cpp); - 双击打开:双击节点会通过
setCurrentNoteFromNoteId()切换当前笔记(noterelationscene.cpp),节点悬停时还会显示包含笔记名与“双击打开”提示的工具提示。
面板的刷新时机
关系图并非常驻刷新。主窗口在切换当前笔记、或笔记内容被保存后更新图:
- 切换笔记时调用
updateNoteGraphicsView()(mainwindow.cpp),且只有面板可见时才真正执行绘制; - 笔记写入磁盘后,
NoteIndexManager::storeUpdatedNotesToDisk()也会调用updateNoteGraphicsView()刷新关系(noteindexmanager.cpp)。
关系的层级展开与图布局算法
多级递归与“几个层级深度”
关系图以当前笔记为根节点,递归地找出每一层笔记所链接的笔记,直到达到 3 层深度(level < 3 时继续递归,见 noterelationscene.cpp)。每一层递归中:
- 调用
findLinkedNotes()找出当前笔记链接到的全部笔记; - 已出现过的笔记(按笔记 ID 去重,记录在
m_noteItems哈希表中)不会重复创建节点,但会重复连线,从而体现双向/网状关系; - 递归深度通过节点边框粗细区分:根节点边框最粗(笔宽
max(5 - level, 2)),越深越细。
同心圆布局算法
链接笔记围绕父节点按圆周均布排列(calculateRadialPosition,noterelationscene.cpp):
- 角度按
2π / 总数等分; - 半径基础值为
250像素,当链接笔记超过 5 个时,每多一个半径增加20像素; - 每深入一层,半径再减去
level * 60,使深层节点更靠近中心,避免层级间重叠; - 若新节点位置与已有节点碰撞,会尝试在 ±75 像素范围内随机偏移(最多尝试 10 次)。
节点渲染
每个节点是一个圆角矩形(NoteItem),白底黑框,居中显示笔记名(noterelationscene.cpp);连线为深灰色虚线(Qt::DashLine,线宽 2),视觉上清晰地区分“笔记节点”与“关系连线”。
后台收集机制:不打断你的工作流
原文档特别强调:关系的收集在后台进行,你可以一边继续工作一边等待关系图完成。这一体验由 Qt 的 QtConcurrent::run() 线程池机制保证(noterelationscene.cpp):
- 绘制前先调用
stopDrawing()取消正在运行的旧线程,并等待其真正结束; - 在后台线程中执行关系收集:遍历全部笔记(
Note::fetchAll())并递归找出链接关系; - 图形项(节点与连线)的创建在后台线程完成,但添加进场景(
addItem)必须回到 GUI 线程——通过自定义信号addItemRequested配合Qt::QueuedConnection队列连接实现(noterelationscene.h),避免多线程直接操作QGraphicsScene引发的计时器与渲染错误; - 后台线程使用独立的内存数据库连接(
DatabaseService::createSharedMemoryDatabase()+applySharedMemoryDatabasePragmas()),因为同一个数据库连接不能在多个线程中共享;线程结束后立即removeDatabase()清理连接; - 线程执行期间若面板数据源变化,新绘制请求会先取消旧线程,保证图始终与最新笔记内容一致。
这套“后台算、前台画”的设计,正是关系收集不阻塞编辑器的根本原因。
小结
笔记关系面板把“笔记间的 Markdown 链接”转化为可视化的关系网络:通过 Note link 对话框或手写链接建立关系,在 Window / Panels 菜单开启面板,用滚轮缩放、拖拽节点、双击打开笔记完成浏览;底层由递归圆周布局组织多级节点,由后台线程完成关系收集并通过队列信号安全地绘制图形。无论是日常整理知识库,还是检查笔记间的引用网络,这个面板都是理解 QOwnNotes 笔记互联结构的直观入口。
相关资源
- 官方文档原文:note-relations.md(英文)
- 核心实现:noterelationscene.h、noterelationscene.cpp
- 链接识别逻辑:note.cpp
- 链接对话框:linkdialog.cpp
- 集成与刷新:mainwindow.cpp、noteindexmanager.cpp
- 单元测试:test_notes.cpp