思源笔记 SiYuan v3.1.21 版本解析反链面板悬浮窗、标签搜索转义与 Electron 升级细节【免费下载链接】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.21 是一个以「细节打磨」为核心的维护版本官方 Overview 将其概括为 This version improves some details。本篇文章以该版本官方变更日志为主体结合仓库中的前端 TypeScript 源码app/src与内核 Go 源码kernel实现逐一拆解 10 项增强、1 项缺陷修复、1 项重构与 2 项开发改进背后的原理。读完你将理解反链面板的块标悬浮窗如何触发、文档树刷新与列表渲染性能优化落在何处、标签搜索转义缺陷为何会导致匹配异常以及 PWA 主题色适配与 Electron 升级对桌面端的影响。Overview一次聚焦「细节」的版本迭代从变更结构看v3.1.21 的改动集中在前端交互层文档树Doc Tree刷新、反链面板Backlink、列表项拖拽、属性搜索、块级选择、鼠标框选等编辑器体验外加一项涉及 PWA 的浏览器端适配与一项 Electron 桌面端运行时升级。这类版本通常不引入新的概念模型而是对既有功能的响应速度、边界行为与视觉一致性做修正适合需要稳定体验的日常用户直接升级。Enhancement十项交互与性能增强详解1. 创建文档时文档树刷新改进issue 12109在旧行为中新建文档后文档树Doc Tree的刷新时机与用户预期不一致——例如新建的文档没有及时出现在树中或在刷新过程中丢失了当前展开状态。该版本改进了创建文档后的树刷新逻辑使树结构变更与用户操作闭环更紧凑。从实现侧看文档树由 app/src/util/Tree.ts 统一维护面板实例如反链面板均通过Tree的updateData方法更新节点数据参见 app/src/layout/dock/Backlink.ts。可以推断本次改动主要调整了创建文档事件触发树刷新的时序与去重逻辑避免在同一批次操作中重复渲染整棵树。2. 反链面板支持悬停块标打开悬浮窗issue 13253这是本版本最具交互价值的增强在反链面板Backlink与提及Mentions列表中鼠标悬停在条目左侧的块标block icon上即可打开内容预览的悬浮窗而无需点击展开。该改动显著降低了「查看引用上下文」的操作成本。反链面板的实现位于 app/src/layout/dock/Backlink.ts面板主体由上下两个区块组成——上方backlinkList引用我Backlinks与下方backlinkMList提及我Backmentions面板头部同时提供筛选、刷新、排序、展开/收起、布局切换等操作入口见 Backlink.ts。每个条目通过toggleItem调用内核接口/api/ref/getBacklinkDoc拉取单篇文档内的高亮引用片段并用Protyle渲染为可交互的块级预览见 Backlink.ts。悬停块标触发悬浮窗即复用了这一渲染管线将其挂载到悬停目标上而非等待点击。值得一并了解的是反链面板背后完整的数据链路面板初始化与搜索时调用/api/ref/getBacklink2见 kernel/api/ref.go该接口同时返回backlinks、backmentions与对应的linkRefsCount、mentionsCount计数并支持sort/mSort排序模式、k/mk双向关键词过滤、containChildren是否包含子块参数若目标块位于加密笔记本请求需携带notebook参数走GetBacklink2InBox加密查询分支见 kernel/api/ref.go。面板还支持按文档名、创建时间、修改时间多种排序模式showSortMenu见 Backlink.ts并通过saveStatus将每篇文档的展开状态、滚动位置持久化在this.status中切换文档后自动恢复见 Backlink.ts。3. 适配 PWA 标题栏颜色issue 13780浏览器端以 PWA 方式安装思源后标题栏颜色此前可能与应用主题不协调。该版本为 PWA 页面动态写入meta nametheme-color其取值来自当前主题的 CSS 变量--b3-body-background从而让浏览器标题栏颜色与编辑器背景色保持同步。相关实现见 app/src/util/assets.tsif (!window.webkit?.messageHandlers !window.JSAndroid !window.JSHarmony (serviceWorker in window.navigator) (caches in window) (fetch in window) navigator.serviceWorker) { document.head.insertAdjacentHTML(afterbegin, meta nametheme-color content${getComputedStyle(document.body).getPropertyValue(--b3-body-background).trim()}); }注意该分支通过/// #if BROWSER编译条件限定仅在纯浏览器非桌面端、非移动端 WebView环境生效PWA 应用清单位于 app/stage/manifest.webmanifest其display_override包含window-controls-overlay、fullscreen、standalone等模式theme-color的动态注入正是对这些显示模式下的视觉一致性补充。4. 改进列表项拖拽时的幽灵占位效果PR 13821拖拽列表项list item时出现的「幽灵占位」ghosting此前可能遮挡内容或位置偏移。本版本调整了拖拽过程中的占位渲染逻辑。列表项渲染与伪元素布局在 app/src/protyle/wysiwyg 目录下的渲染层维护与之配套PR 13959见下文 Development 小节同时优化了列表项伪元素pseudo-element的布局二者共同作用于列表块的稳定渲染。5. 改进属性搜索与高亮issue 13843属性Attribute搜索在命中关键字后结果中的匹配片段现在能更准确地进行高亮。思源中属性搜索通过/api/search/searchAttr一类接口查询 SQL 索引前端在结果渲染时对匹配片段做标记。该改进主要落在标记算法的边界处理上使包含子串歧义的关键字例如同时命中属性名与属性值能获得一致的高亮范围。6. 提升文档树列表性能issue 13844列出文档树listing doc tree是高频操作大仓库下容易出现卡顿。本次优化重点在减少文档树节点数据的全量重绘与 DOM 重建。文档树的展开/收起状态由Tree实例维护toggleItem、toggleClick等回调见 Backlink.ts可以推断优化方向是仅在状态变化的节点上做局部更新而非整树updateData同时配合服务端接口的数据裁剪降低单次返回的节点体积。7. 浏览器剪藏扩展支持移除图片链接issue 13941思源官方的浏览器剪藏扩展Web Clipper在剪藏网页时此前图片会保留原站链接本版本新增了「移除图片链接」能力即剪藏时剥离图片的href/src外链仅保留图片本身避免剪藏内容被原站外链干扰或失效。该功能属于剪藏扩展侧逻辑仓库中与之对应的剪藏后清理管线位于内核导入模块可参考 kernel/model/import.go 的 HTML 清洗流程。8. 为数据库绑定块的主键增加图标issue 13945在数据库/属性视图Attribute View中绑定到数据库行的块block此前与普通块在视觉上不易区分。本版本为其主键primary key对应的块增加了专门图标帮助用户快速识别「这是数据库绑定块的主键列」。该图标渲染与数据库行/单元格的块标逻辑位于 app/src/protyle/render/av 目录如 blockAttr.ts 中的block__icon渲染模式。9. 删除图片间空格将产生换行issue 13949这是 Markdown 语义细节的修正当两个图片块之间的空格被删除时此前图片可能仍保持同一段落即「中间留空」的视觉表现本版本使其正确产生换行符合块级元素预期的排版结果。该行为与 kernel/model/md2html.go 中 Markdown 到 HTML 的段落划分规则相关图片间仅有的空格被删除后两个图片块不再共享段落边界从而自然断行。10. 改进鼠标框选块PR 14010编辑器内使用鼠标框选mouse selection多个块时选择范围此前可能包含非预期块或遗漏边界块。本版本优化了框选命中判定使选择结果与用户视觉期望一致。选择与光标语义在 app/src/protyle/wysiwyg 的选区管理模块维护框选事件的命中判断同时与「块标 hover 不触发 号」的既有规则见 app/src/protyle/gutter/index.ts协同工作。Bugfix标签搜索转义修正issue 13919本版本唯一列出的缺陷修复属于安全性/正确性关键修复标签Tag搜索未正确转义。标签搜索的前端入口调用/api/search/searchTag见 app/src/protyle/hint/extend.ts内核实现位于 kernel/api/search.go接收关键词k调用model.SearchTags(k)返回{tags, k}。而 kernel/model/tag.go 中的实现涉及两点func SearchTags(keyword string) (ret []string) { ret []string{} sql.FlushQueue() labels : labelBlocksByKeyword(keyword) keyword strings.Join(strings.Split(keyword, ), search.TermSep) for label : range labels { if keyword { ret append(ret, util.EscapeHTML(label)) continue } _, t : search.MarkText(label, keyword, 1024, Conf.Search.CaseSensitive) ret append(ret, t) } sort.Strings(ret) return }可以看到关键词为空时对标签做了util.EscapeHTML而非空关键词路径则通过search.MarkText生成带高亮标记的结果。修复前的问题在于当关键词包含正则特殊字符如#、、(、[等时MarkText的匹配与标记逻辑未对这些字符做转义导致匹配范围异常甚至返回空结果同时结果中的标签文本如果直接拼接进 HTML特殊字符可能被误解析。本版本的修复即是对匹配关键字与输出文本两侧的转义补齐保证任意标签名包括含特殊字符的标签都能被正确搜索、命中与高亮展示。顺带一提SearchTags底层通过labelBlocksByKeyword调用sql.QueryTagSpansByKeyword查询 SQL 索引中的标签 span并按块 ID 去重后聚合见 kernel/model/tag.go因此标签搜索本质上是基于块级索引的实时查询而非全文扫描。Refactor升级至 Electron v33.4.0issue 14009桌面端运行时从旧版本升级至 Electron v33.4.0。该升级主要带来 Chromium 渲染内核的版本提升直接受益于编辑器渲染层Protyle对最新 CSS 特性如:has()、color-mix()等的兼容性以及 Web 安全修复。当前仓库主分支的 Electron 依赖已演进至更高版本app/package.json 中electron: 42.6.1但 v3.1.21 作为历史版本锚定 v33.4.0。桌面端入口逻辑位于 app/electron/main.jsElectron 构建配置分散在 app/electron-builder.yml 及各平台变体electron-builder-linux.yml、electron-builder-darwin.yml、electron-builder-arm64.yml等中。若需验证该版本桌面端行为可参考这些构建配置还原对应运行环境。Development面向插件生态与样式体系的两项改进1. 为 pasteText 一并触发 bus paste 事件PR 13927思源的事件总线event bus此前在「粘贴 HTML/富文本」时触发paste事件而纯文本粘贴pasteText路径未触发。本版本补全了这一事件流使插件可以统一监听paste事件拦截/处理所有粘贴来源而无需区分剪贴板内容类型。事件总线的连接与分发机制可在 app/src/util/events.tseventBus中查看插件侧 API 定义位于 kernel/plugin/api_event.go。2. 改进字号 CSS 与列表项伪元素布局PR 13959这是与 PR 13821列表项拖拽幽灵占位配套的样式层改进调整了字号相关 CSS 变量--b3-font-size体系的继承层级并重构了列表项list item伪元素如块标、折叠箭头的占位元素的布局方式使拖拽占位、列表缩进与自定义主题的字号覆盖行为更加一致。相关样式源文件位于 app/src/assets/scss 目录如protyle相关 scss桌面/移动端主题分别定义于 app/appearance/themes 下的 daylight 与 midnight 主题。如何获取与验证 v3.1.21该版本的官方下载渠道为 B3log 官网下载页与 GitHub Releases 页面此处不赘述外部链接。仓库内 app/changelogs/v3.1.x/v3.1.21/v3.1.21.md 即本篇文章依据的原始变更文档同目录还提供简体中文.zh-CN.md与繁体中文.zh-TW.md译本可供对照。若希望在当前仓库中复现相关代码路径建议按如下顺序阅读反链面板完整实现app/src/layout/dock/Backlink.ts含排序、过滤、状态恢复、悬浮预览的挂载逻辑反链内核接口kernel/api/ref.gogetBacklink2、getBacklinkDoc、refreshBacklink与路由注册 kernel/api/router.go标签搜索修复链路app/src/protyle/hint/extend.ts → kernel/api/search.go → kernel/model/tag.goPWA 主题色适配app/src/util/assets.ts 与 app/stage/manifest.webmanifestElectron 升级与构建配置app/package.json 与 app/electron-builder.yml。小结v3.1.21 的价值不在于新增了多少重量级功能而在于把编辑器与面板的高频路径打磨得更顺手反链面板悬停块标即可预览上下文文档树刷新与列表渲染更轻快标签搜索对特殊字符更健壮PWA 与桌面端的外观适配更完整。对于使用思源笔记管理大量块级引用关系的用户而言反链面板的交互改进与标签搜索修复是本次升级中最值得直接受益的两处改动。【免费下载链接】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），仅供参考
