QOwnNotes 笔记关系(Note Relations)面板深度指南:链接语法、图布局与后台收集机制

原创2026-10-13 20:49:231,413 阅读
文章标签:桌面应用知识管理富文本插件系统跨平台

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):

  1. 绘制前先调用 stopDrawing() 取消正在运行的旧线程,并等待其真正结束;
  2. 在后台线程中执行关系收集:遍历全部笔记(Note::fetchAll())并递归找出链接关系;
  3. 图形项(节点与连线)的创建在后台线程完成,但添加进场景(addItem)必须回到 GUI 线程——通过自定义信号 addItemRequested 配合 Qt::QueuedConnection 队列连接实现(noterelationscene.h),避免多线程直接操作 QGraphicsScene 引发的计时器与渲染错误;
  4. 后台线程使用独立的内存数据库连接(DatabaseService::createSharedMemoryDatabase() + applySharedMemoryDatabasePragmas()),因为同一个数据库连接不能在多个线程中共享;线程结束后立即 removeDatabase() 清理连接;
  5. 线程执行期间若面板数据源变化,新绘制请求会先取消旧线程,保证图始终与最新笔记内容一致。

这套“后台算、前台画”的设计,正是关系收集不阻塞编辑器的根本原因。

小结

笔记关系面板把“笔记间的 Markdown 链接”转化为可视化的关系网络:通过 Note link 对话框或手写链接建立关系,在 Window / Panels 菜单开启面板,用滚轮缩放、拖拽节点、双击打开笔记完成浏览;底层由递归圆周布局组织多级节点,由后台线程完成关系收集并通过队列信号安全地绘制图形。无论是日常整理知识库,还是检查笔记间的引用网络,这个面板都是理解 QOwnNotes 笔记互联结构的直观入口。

相关资源

登录后查看全文
QOwnNotes