思源笔记 v3.1.20 版本解析:编辑器细节打磨、数据库字段改进与插件 API 更新

原创2026-09-09 10:09:331,828 阅读
文章标签:知识管理桌面应用后端前端AI Agent人工智能MCP 服务MCP Clients插件系统富文本

思源笔记 v3.1.20 版本解析:编辑器细节打磨、数据库字段改进与插件 API 更新

本文基于思源笔记(SiYuan)开源仓库中 v3.1.20 的官方更新日志(v3.1.20_zh_CHT.md、v3.1.20_zh_CN.md)展开,逐一解析该版本 21 项功能改进、1 项开发重构与 2 项插件 API 变更,并结合仓库前端(app/src)与内核(kernel)源码,说明每一项改动背后的实现位置与使用影响。读完本文,你可以完整了解 v3.1.20 的改动全貌,掌握新增插件 API openSetting 的用法、addFloatLayer 参数调整后的正确调用方式,以及 PlantUML、PDF 标注、移动端代理等配置在源码中的落点。

版本总览:一次面向细节的稳定性迭代

v3.1.20 的官方概述只有一句话——"该版本改进了一些细节",但实际变更清单覆盖了编辑器交互、行级元素解析、数据库字段、超级块与列表编辑、反向链接、PDF 标注、剪藏扩展、移动端以及开发者 API 等多个维度,共 21 项功能改进。这说明该版本的主基调是"在既有功能体系上做精细化打磨",而非引入全新的大模块。

按主题可归纳为以下六类:

主题类别 涉及变更项数 典型改进
编辑器交互体验 5 页签拖动高亮、工具栏隐藏、窗口控件避让、拖拽改进
行级元素与解析 4 复制移除 Markdown 标记、行级代码/下划线解析
数据库(属性视图) 2 字段内容转义、更改字段类型
超级块、列表与反向链接 5 合并约束、反向链接传递与计数
导入、PDF、PlantUML、剪藏 4 PDF 标注转文本、PlantUML 超链接点击
移动端与网络 2 Android 保活通知、移动端代理设置

以下按主题逐项解析。

编辑器交互体验改进

页签拖动高亮

改进页签拖动时的高亮反馈(PR 13549),让用户在拖拽页签(Tab)过程中能更清晰地看到目标插入位置。此项属于前端布局模块的视觉反馈优化,相关拖拽逻辑位于 app/src/layout 下的布局管理代码中。

工具栏的显示与避让

两项改动共同优化了工具栏的可用性:

  • 当鼠标按在工具栏以外的元素上时隐藏工具栏(issue 13653):改进了编辑器浮动工具栏的显隐判定,避免鼠标点击正文后工具栏仍残留遮挡视线。
  • 避免窗口控件覆盖 SiYuan 工具栏按钮(PR 13771):主要针对桌面端窗口,确保系统窗口控制按钮(最小化/最大化/关闭)不会与思源自身的工具栏按钮发生层叠覆盖。

文档、大纲、数据库和块的拖拽

"改进文档、大纲、数据库和块的拖动"(issue 13785)属于跨模块的拖拽体验统一优化,覆盖了左侧文档树、大纲面板、数据库视图以及编辑器内的块拖拽场景,可视为该版本交互层的一次集中梳理。

行级元素与 Markdown 解析改进

复制行级元素时移除 Markdown 标记符

此前的复制行为可能把行级元素背后的 Markdown 标记符(如行级代码的反引号、下划线的 == 等)一并带出,导致粘贴到其他应用时出现多余的符号。v3.1.20 改为复制时剥离标记符,只保留纯文本内容,提升了"复制—粘贴到外部"的体验。

支持复制图片文件后多次粘贴

修复了复制图片文件后只能粘贴一次的问题(issue 13736),现在复制一张图片后可以在文档中连续多次粘贴。这与前端的剪贴板处理逻辑相关,对应仓库 app/src/asset 目录下的资源处理代码。

改进行级代码元素解析

行级代码(inline code)的解析逻辑得到改进(issue 13754),主要涉及 Markdown 解析边界情况的处理——例如行内代码中的特殊字符、相邻标记等场景。思源使用 app/stage/protyle 中内置的 Lute 引擎完成 Markdown 解析。

改进下划线元素解析

下划线元素解析同样得到改进(issue 13768),保证 ==文本== 之类的标记在复杂上下文(嵌套、边界符号)中仍能被正确识别与渲染。

数据库(属性视图)字段改进

主键、关联和汇总字段的内容转义

数据库(属性视图)的主键、关联(relation)和汇总(rollup)字段在展示时,其内容中的特殊字符可能被错误解析。该版本改进了这些字段的内容转义(issue 13704),确保特殊字符按字面值展示。数据库相关的表与字段渲染逻辑分布在 kernel/av(内核属性视图模块)与 app/src/protyle(前端渲染)中。

改进更改数据库字段类型

当用户在属性视图中把某个字段从一种类型切换为另一种类型时,涉及值的兼容转换与空值处理。该版本改进了这一流程(issue 13797),降低误操作导致的数据异常风险。

超级块、列表与反向链接

超级块合并约束

当超级块的所有子块都被选中时,不再支持"合并为超级块"(issue 13729)。这是一个合理的边界约束:全部子块选中再合并会产生语义歧义,因此直接禁用该操作。

改进列表超级块编辑

列表项作为超级块的编辑场景(issue 13764)得到改进,主要涉及列表嵌套层级下的块操作正确性。相关块操作逻辑位于 kernel/treenode 目录。

反向链接的传递与计数

反向链接是本版本改进的重点方向之一,共涉及三项:

  • 改进列表项、超级块和引用块的反向链接传递(issue 13776):修复了嵌套结构(列表项、超级块、引用块)中反向链接未能正确向上传递的问题;
  • 文档块标题的反向链接计数包括子块(issue 13791):文档块标题上显示的反向链接数量现在会包含其所有子块产生的引用,统计口径更完整;
  • 改进块内容统计(issue 13759):配合反向链接与字数统计的底层计算逻辑做了修正。

反向链接的生成与聚合逻辑位于 kernel/model/backlink.go。

PDF 标注转文本与 PlantUML 超链接

PDF 标注支持转换为文本

v3.1.20 支持将 PDF 标注转换为文本(issue 13742),意味着用户可以把在 PDF 上的高亮、批注等标注内容抽取为可编辑的文本。内核中 PDF 相关能力(链接标注提取等)位于 kernel/model/pdf.go。

支持点击 PlantUML 图表超链接

PlantUML 图表中的超链接此前无法点击跳转,该版本支持点击(issue 13801)。PlantUML 的渲染服务地址由配置项 plantUMLServePath 控制,默认值为 https://www.plantuml.com/plantuml/svg/~1,其默认值定义可见 kernel/conf/editor.go,并在 kernel/api/setting.go 的配置处理中做了兜底补全。该配置同样可在界面"设置 → 编辑器"中修改。

导入、剪藏与移动端

改进导入配置

导入功能的配置项处理得到改进(issue 13767),涉及导入时的路径与格式选项的解析正确性。思源内核导入相关逻辑位于 kernel/model/import.go。

改进浏览器剪藏扩展的懒加载图片处理

针对浏览器剪藏扩展(Web Clipper)抓取页面时遇到的懒加载图片(data-src 等)抓取不全的问题,该版本做了改进(issue 13810),使剪藏结果中的图片能更完整地落入文档。

支持通过网络伺服设置移动端代理

当通过局域网/网络伺服访问移动端时,现在支持设置代理(issue 13784),方便在受限网络环境下使用移动端连接桌面内核。网络伺服相关能力由 kernel/server/serve.go 提供。

支持在 Android 上设置保活通知文本

Android 端新增保活通知文本的自定义能力(issue 13815),用户可以在通知栏中看到更友好的常驻通知文案,降低进程被系统回收的概率。

开发重构:升级至 Electron v32.2.8

本版本将桌面端运行时从旧版 Electron 升级至 v32.2.8(issue 13752),属于安全性与稳定性驱动的例行升级。桌面端构建相关配置位于 app/electron-builder.yml 及各平台的构建文件中(如 app/electron-builder-linux.yml),Electron 主进程入口为 app/electron/main.js。

插件 API 更新(面向开发者)

v3.1.20 对插件 API 做了两项调整,对插件开发者有直接影响。

新增插件 API openSetting

新增插件 API openSetting(PR 13761),用于以编程方式打开插件的设置对话框。其前端实现位于 app/src/plugin/index.ts,核心逻辑如下:

public openSetting() {
    if (!this.setting) {
        return;
    }
    this.setting.open(this.displayName || this.name);
}

即:仅当插件声明了 setting(配置面板)时才打开设置对话框,标题取插件的显示名或名称。该 API 已被导出到插件 API 集合中,见 app/src/plugin/API.ts。此外,内核侧也提供了对应的设置对话框辅助能力,插件还可在顶部工具栏菜单中通过 openSetting 入口打开设置(相关调用见 app/src/plugin/openTopBarMenu.ts)。

使用示例(插件代码中):

// 插件需声明 setting 配置面板
this.openSetting();

更改插件 API addFloatLayer 的参数

addFloatLayer 的参数由原先的多个独立参数改为聚合为一个 options 对象(issue 13816)。从当前源码 app/src/plugin/index.ts 可以确认其新签名:

public addFloatLayer = (options: {
    refDefs: IRefDefs[],
    x?: number,
    y?: number,
    targetElement?: HTMLElement,
    originalRefBlockIDs?: IObject,
    isBacklink: boolean,
}) => {
    window.siyuan.blockPanels.push(new BlockPanel({
        app: this.app,
        originalRefBlockIDs: options.originalRefBlockIDs,
        targetElement: options.targetElement,
        isBacklink: options.isBacklink,
        x: options.x,
        y: options.y,
        refDefs: options.refDefs,
    }));
};

从源码结构看,原有参数(originalRefBlockIDs、targetElement、isBacklink、x、y、refDefs)全部被保留在 options 对象内部,因此已使用旧签名调用 addFloatLayer 的插件需要将调用方式改写为:

// 旧:this.addFloatLayer(app, originalRefBlockIDs, targetElement, x, y, refDefs, isBacklink);
// 新:聚合为 options 对象
this.addFloatLayer({
    originalRefBlockIDs: ids,
    targetElement: el,
    x: 0,
    y: 0,
    refDefs: refs,
    isBacklink: false,
});

该 API 用于在编辑器内打开一个基于块引用的浮动面板(BlockPanel),常用于实现引用浮层、反链面板类功能。

下载与升级

v3.1.20 已在各平台发布,桌面端可通过官方下载页与各平台发布渠道获取,移动端可通过应用商店升级。升级后建议关注上述数据库字段、超级块、反向链接相关的行为变化,插件开发者则务必检查 addFloatLayer 的调用签名是否已适配新参数形式。

小结

v3.1.20 是思源笔记在细节层面的一次集中打磨:编辑器交互与行级元素解析更顺手、数据库字段处理更健壮、反向链接统计口径更完整,同时为移动端和剪藏场景补齐了多项实用能力。对开发者而言,新增的 openSetting API 降低了插件配置面板的接入成本,而 addFloatLayer 的参数聚合则要求插件作者跟进适配。如果你想深入验证文中提到的每处实现细节,可直接在仓库中查阅对应的源码路径。

登录后查看全文
siyuan