思源笔记 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导读思源笔记SiYuanv3.1.20 是一个以细节改进为主题的版本共包含 21 项增强、1 项重构与 2 项插件 API 变更。本文基于官方 changelogv3.1.20.md并结合仓库源码逐条梳理该版本在编辑器交互、数据库、PDF 批注、移动端与插件开发层面的实际改动帮助你快速判断升级收益并了解这些改动背后的实现原理。一、版本概览类别数量代表改动Enhancement21标签页拖拽高亮、数据库字段转义、PDF 批注转文本、内联代码解析优化等Refactor1升级 Electron 至 v32.2.8Development2新增插件 APIopenSetting、调整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文本高亮批注通过textLayer获取选中范围将rangeContents.textContent清洗换行与空字符后写入批注内容见 anno.ts并记录起始页、结束页坐标区域高亮矩形框批注在 anno.ts 中会把选区内容写入data-content属性后续可据此还原或转换为文本批注内容最终以${idPath} ${content}的形式写回文档见 anno.ts。本次改动即围绕批注内容可再转回普通文本打通闭环从 PDF 文本层选区生成的批注可转换为文档内的普通文本块便于后续检索、摘录与整理。配合 v3.1.20 同时改进的块内容统计Issue #13759字数、块数统计在包含批注引用与子块时也更准确。五、浏览器剪藏与 PlantUML改进浏览器剪藏扩展的懒加载图片处理Issue #13810对使用loadinglazy的图片剪藏时会正确触发加载再抓取避免只截到占位图。支持点击 PlantUML 图内超链接Issue #13801渲染出的 PlantUML 图中若包含可点击链接现在可直接点击跳转无需切回源码模式。六、移动端与网络服务网络伺服时支持移动端代理设置Issue #13784当手机通过网络伺服访问桌面端思源时可在移动端配置代理适应受限网络环境。支持设置 Android 端保活通知文本Issue #13815Android 前台服务的保活通知文案可自定义避免与其他应用通知混淆。七、重构升级 Electron v32.2.8v3.1.20 将桌面端运行时从 Electron 升级至v32.2.8Issue #13752 等构建配置统一管控桌面安装包构建流程无需额外调整。八、插件 API 变更面向插件开发者8.1 新增插件 APIopenSetting新版本为插件对象增加了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 变更插件 APIaddFloatLayer参数调整addFloatLayer用于在页面中创建一个浮动引用/反链面板其参数结构在 v3.1.20 中发生变化Issue #13816public 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.tsPDF 批注模块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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考