企业官网建设流程全解析

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

【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间，让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan

导读

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

一、版本概览

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

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

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：

• 文本高亮批注通过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 等构建配置统一管控，桌面安装包构建流程无需额外调整。

八、插件 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：

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 统一设置面板的打开方式。

参考资源

• 官方变更日志：v3.1.20.md
• 插件基类实现：app/src/plugin/index.ts
• 插件 API 导出：app/src/plugin/API.ts
• 插件顶层菜单：app/src/plugin/openTopBarMenu.ts
• PDF 批注模块：app/src/asset/anno.ts
• 设置面板入口：app/src/config/index.ts

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

【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间，让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan