思源笔记 v3.1.20 更新解读:编辑体验打磨、数据库字段转义与插件 API 扩展

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

思源笔记 v3.1.20 更新解读:编辑体验打磨、数据库字段转义与插件 API 扩展

导读

思源笔记(SiYuan)v3.1.20 是一个以"细节改进"为主题的版本,共包含 21 项增强、1 项重构与 2 项插件 API 变更。本文基于官方 changelog(v3.1.20.md)并结合仓库源码,逐条梳理该版本在编辑器交互、数据库、PDF 批注、移动端与插件开发层面的实际改动,帮助你快速判断升级收益,并了解这些改动背后的实现原理。

一、版本概览

类别 数量 代表改动
Enhancement 21 标签页拖拽高亮、数据库字段转义、PDF 批注转文本、内联代码解析优化等
Refactor 1 升级 Electron 至 v32.2.8
Development 2 新增插件 API openSetting、调整 addFloatLayer 参数

该版本没有破坏性变更,绝大多数改动面向日常编辑体验与数据完整性,属于"低风险、高收益"的常规升级。

二、编辑器与交互体验增强

2.1 拖拽与窗口交互

  • 改进标签页拖拽高亮(PR #13549):拖拽标签页时的高亮反馈更加准确,减少误操作。
  • 点击工具栏以外元素时隐藏工具栏(Issue #13653):此前工具栏可能因焦点切换而滞留,本次改为"按下非工具栏元素即收起",与常见桌面软件交互习惯保持一致。
  • 避免窗口控制按钮遮挡工具栏按钮(PR #13771):在 Windows 等使用原生窗口控制按钮(最小化/最大化/关闭)的场景下,布局会让出空间,避免顶栏按钮被遮挡。
  • 改进文档、大纲、数据库与块的拖拽(Issue #13785):统一优化了这几类对象在拖拽时的定位与目标判定逻辑。

2.2 复制、粘贴与元素解析

  • 复制行内元素时移除 Markdown 标记(Issue #13735):复制加粗、斜体、行内代码等行内元素到外部时,不再携带 **、` 等 Markdown 标记,粘贴结果更干净。
  • 支持复制图片文件后多次粘贴(Issue #13736):剪贴板中的图片不再是一次性消费,可连续粘贴到多个文档位置。
  • 改进内联代码元素解析(Issue #13754)与下划线元素解析(Issue #13768):这两项涉及行内标记(inline marker)的解析边界处理,例如 a 与 ` 混排、连续下划线等边界情况。

2.3 列表与超级块

  • 列表所有子块被选中时,禁止合并为超级块(Issue #13729):超级块(super block)用于聚合逻辑上独立的块,而列表项与其子块本就属于同一列表容器,全部选中时合并会产生冗余嵌套,因此版本中移除了该入口。
  • 改进列表超级块编辑(Issue #13764):优化了列表内超级块的光标定位与结构操作。
  • 改进列表项、超级块与引用块的反链传播(Issue #13776):修复了当文档标题、列表项等块被引用后,子块反链计数与传播不完整的问题。
  • 文档块标题的反链计数包含子块(Issue #13791):此前引用块内只统计直接命中的块,本次将子块中的引用一并计入,使反链数量更贴近真实引用关系。

三、数据库(属性视图)改进

  • 改进数据库主键、关系与汇总字段的转义(Issue #13704):数据库主键(Primary Key)、关系(Relation)、汇总(Rollup)字段在写入时会对引号、反斜杠等特殊字符做正确转义,避免字段值中包含特殊字符时产生解析错乱。这是本次版本中对数据完整性影响最直接的一项修复。
  • 改进修改数据库字段类型(Issue #13797):切换字段类型时(如文本转数字、单选转多选),系统会进行更严谨的兼容性校验与数据迁移提示,降低误操作导致的数据丢失风险。

四、PDF 批注支持转换为文本

PDF 批注支持转换为文本(Issue #13742)是本版本的一项亮点能力。在思源中,PDF 批注(文本高亮、区域高亮)由前端资产管理模块承载,核心实现在 app/src/asset/anno.ts:

  • 文本高亮批注通过 textLayer 获取选中范围,将 rangeContents.textContent 清洗换行与空字符后写入批注内容(见 anno.ts),并记录起始页、结束页坐标;
  • 区域高亮(矩形框)批注在 anno.ts 中会把选区内容写入 data-content 属性,后续可据此还原或转换为文本;
  • 批注内容最终以 <<${idPath} "${content}">> 的形式写回文档(见 anno.ts)。

本次改动即围绕"批注内容可再转回普通文本"打通闭环:从 PDF 文本层选区生成的批注,可转换为文档内的普通文本块,便于后续检索、摘录与整理。配合 v3.1.20 同时改进的块内容统计(Issue #13759),字数、块数统计在包含批注引用与子块时也更准确。

五、浏览器剪藏与 PlantUML

  • 改进浏览器剪藏扩展的懒加载图片处理(Issue #13810):对使用 loading="lazy" 的图片,剪藏时会正确触发加载再抓取,避免只截到占位图。
  • 支持点击 PlantUML 图内超链接(Issue #13801):渲染出的 PlantUML 图中若包含可点击链接,现在可直接点击跳转,无需切回源码模式。

六、移动端与网络服务

  • 网络伺服时支持移动端代理设置(Issue #13784):当手机通过"网络伺服"访问桌面端思源时,可在移动端配置代理,适应受限网络环境。
  • 支持设置 Android 端保活通知文本(Issue #13815):Android 前台服务的保活通知文案可自定义,避免与其他应用通知混淆。

七、重构:升级 Electron v32.2.8

v3.1.20 将桌面端运行时从 Electron 升级至 v32.2.8(Issue #13752)。该版本属于 Chromium 内核的常规安全性与稳定性更新,也顺带解决了部分平台上的窗口控制按钮与工具栏布局问题(见 PR #13771)。升级由 electron-builder.yml 等构建配置统一管控,桌面安装包构建流程无需额外调整。

八、插件 API 变更(面向插件开发者)

8.1 新增插件 API:openSetting

新版本为插件对象增加了 openSetting() 方法,用于以编程方式打开插件自身的设置界面。

实现层面,app/src/plugin/index.ts 中的逻辑为:

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

即:只有插件声明了 setting(设置面板实例)时才生效,并自动以 displayName 或插件名作为设置面板标题打开。

在顶层菜单中,openTopBarMenu.ts 会检测插件是否具备设置能力(plugin.setting || plugin.__proto__.hasOwnProperty("openSetting")),并在右键菜单中注入"设置"项;同时插件入口 API.ts 已将该 API 导出到全局 window.siyuan 命名空间。

插件侧用法:

class MyPlugin extends Plugin {
    onload() {
        // 注册设置面板
        this.setting = new Setting({ confirmCallback: () => this.save() });
        // 之后可在任意事件中打开设置
        this.eventBus.on("click-open-setting", () => this.openSetting());
    }
}

8.2 变更插件 API:addFloatLayer 参数调整

addFloatLayer 用于在页面中创建一个浮动引用/反链面板,其参数结构在 v3.1.20 中发生变化(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,
    }));
};

对比旧版,参数由散落的独立入参改为统一的 options 对象,其中 refDefs(引用定义列表)与 isBacklink(是否为反链面板)为必填项,x/y 用于指定面板出现位置,targetElement 用于锚定触发元素,originalRefBlockIDs 用于标记原始引用来源。如果你维护的插件调用了该 API,需要按新的 options 结构迁移。

九、升级建议

  • 普通用户:v3.1.20 全部为细节增强与 bug 修复,无破坏性变更,建议直接升级;特别关注数据库字段转义修复(#13704)与复制粘贴体验改进(#13735、#13736)。
  • PDF 深度用户:批注转文本能力(#13742)值得重点体验,可将高亮批注沉淀为可检索的正文内容。
  • 插件开发者:核对插件是否调用过 addFloatLayer,如有需按新 options 参数结构迁移;可选用新增的 openSetting() API 统一设置面板的打开方式。

参考资源

注:文中 Issue/PR 链接为官方 GitHub 讨论编号,便于核对原始讨论;所有实现细节均可在当前仓库对应源码文件中验证。

登录后查看全文
siyuan