news 2026/9/10 22:00:31

SiYuan v3.3.2 版本详解：数据库筛选细化、代码片段 disabledInPublish 新字段与 expandDocTree 插件函数

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
SiYuan v3.3.2 版本详解：数据库筛选细化、代码片段 disabledInPublish 新字段与 expandDocTree 插件函数

SiYuan v3.3.2 版本详解：数据库筛选细化、代码片段 disabledInPublish 新字段与 expandDocTree 插件函数

【免费下载链接】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.3.2 是一次以“细节打磨”为主的版本：它在数据库（Database）视图的字段编辑、汇总/日期筛选、分组交互上做了多处改进，并新增了面向发布服务的disabledInPublish元数据字段与插件函数expandDocTree。本文基于官方变更记录 v3.3.2 中文版（同版本还有 英文版 与 繁体中文版），结合仓库源码逐项拆解这些变更的实际行为、参数含义与底层实现，帮助开发者与进阶用户完整理解该版本的变更面。

版本概述

官方概述只有一句话：“此版本改进了一些细节”。但从变更记录看，v3.3.2 的改动集中在三条主线上：

  1. 编辑器与块操作体验：折叠标题的复制/剪切语义调整、代码块复制行为、文件拖入、HTML 表格剪藏等；
  2. 数据库（Database）视图：字段编辑菜单、汇总字段筛选规则（任一/所有/没有）、日期字段筛选、分组拖动同步、分组视图性能等多处打磨；
  3. 面向开发者/插件生态：代码片段新增disabledInPublish字段、集市插件包元数据新增同名字段、新增插件函数expandDocTree、内核 APIappendBlock、insertBlock、prependBlock的改进。

其中第三类变更在仓库源码中有明确的落地实现，下文会给出对应的文件与关键代码位置。

改进功能逐项解析

编辑器与块操作

  • 折叠标题的复制/剪切改为复制/剪切“标题及其下方块”，并支持多标题复制/剪切：此前对折叠标题做复制/剪切时只处理标题本身，v3.3.2 之后会把标题连同其折叠区域内的子块一起纳入复制/剪切范围，并支持一次选中多个标题批量操作。这一改动与 SiYuan“一切皆块（block）”的模型一致——标题是块的容器边界，复制标题即复制其下的块树。
  • 代码块选择复制时仅复制纯文本：选中代码块内容复制时不再携带额外格式，得到纯净的代码文本，方便粘贴到其他编辑器或终端。
  • 代码块语言提示搜索内容为空时使用默认排序：代码块顶部语言提示（language hint）在搜索框为空时恢复为按默认顺序展示语言列表，避免空搜索导致候选异常。
  • 拖入多个文件到编辑器不再被默认程序打开：修复批量拖入时文件被系统默认程序抢走打开的行为，统一走编辑器内的文件插入流程。
  • 改进 HTML 表格剪藏：优化网页剪藏场景下 HTML 表格转 SiYuan 表格块的还原效果。
  • 点击无文档的笔记本时自动新建文档：在空笔记本上直接点击即可创建首个文档，省去手动“新建文档”的一步操作。

数据库（Database）视图

数据库是 v3.3.2 改动最集中的模块，共 8 条改进：

  • 改进数据库字段编辑菜单：优化数据库字段编辑入口的菜单组织，字段属性的调整路径更顺。
  • 数据库汇总字段筛选规则支持“任一”、“所有”和“没有”：汇总（rollup）字段聚合了关联数据集中的多个值，此前对这类多值结果的筛选语义不明确；v3.3.2 之后可以显式指定匹配规则——
    • 任一（any）：聚合值中至少有一个满足条件即命中；
    • 所有（all）：聚合值全部满足条件才命中；
    • 没有（none）：聚合值中没有任何一个满足条件时命中。 从源码结构看，数据库字段的定义、取值与筛选渲染主要分布在kernel/av模块（如 filter.go）、kernel/sql/av.go（其中包含 rollup 类型字段的处理逻辑）以及按布局拆分的 av_table.go、av_gallery.go、av_kanban.go，筛选规则的语义变化需要前端筛选 UI 与内核查询共同配合。
  • 改进数据库汇总字段筛选：与上一条配套，对汇总字段筛选的整体交互与规则判定做进一步细化。
  • 改进数据库日期字段筛选：日期字段的筛选能力增强，配合下文“修复数据库日期字段无法粘贴 0 点时间”的缺陷修复，日期类数据在数据库中的录入与筛选体验更完整。
  • 数据库中新建数据如果在折叠分组内，不再弹出编辑框：在分组视图（如看板）中，向一个处于折叠状态的分组新增条目时，不再强制弹出编辑弹窗，交互更不打断浏览。
  • 数据库添加选项时禁止编辑：为单选/多选类字段添加选项的过程中，禁止同时对已有选项做编辑，避免录入态下选项值被意外改动。
  • 数据库条目跨分组拖动后，同步更新其他视图中的分组：在某个视图中把条目拖入另一个分组后，同一数据库的其余视图（表格/看板/图库）会同步反映新的分组归属，保证多视图数据一致。
  • 提升数据库分组视图性能：分组视图（如按字段分组的表格/看板）在数据量较大时的渲染性能得到优化。

其他改进

  • 改进闪卡：优化闪卡学习体验。可以确认的是，内核侧闪卡配置定义在 kernel/conf/flashcard.go 的Flashcard结构中，包含新卡上限（newCardLimit，默认 20）、复习卡上限（reviewCardLimit，默认 200）、标记/列表块/超级块/标题块/卡包制卡开关，以及基于 FSRS 算法的requestRetention、maximumInterval、weights参数；本次“改进闪卡”属于该体系上的体验优化。
  • Android 隐藏底部手势导航栏：移动端界面隐藏系统底部手势导航栏，减少遮挡。
  • 浏览器剪藏扩展支持剪藏页面到数据库：剪藏扩展新增“剪藏页面到数据库”的目标，网页可以直接落库为数据库条目。

新增字段disabledInPublish：代码片段与集市插件包

本版本有两个相互对应的disabledInPublish变更：

  1. 代码片段新增字段disabledInPublish，用于标识该片段在“发布服务”中是否被禁用；
  2. 集市（Bazaar）插件包元数据新增同名字段，用于标识插件在发布服务中是否被禁用。

从源码看，该字段贯穿了前端配置 UI、内核配置解析与插件包元数据三层：

  • 类型定义：前端全局类型声明中加入了disabledInPublish: boolean，见 app/src/types/index.d.ts。
  • 代码片段 UI：片段编辑界面提供开关控件，默认关闭（不禁用），见 app/src/config/util/snippets.ts：
    • L119：新建片段时初始化disabledInPublish: false；
    • L196：渲染data-type="disabledInPublish"的b3-switch开关；
    • L233：读取开关状态时取反（未勾选表示不禁用）。
  • 内核配置解析：
    • 结构体字段定义在 kernel/conf/snippet.go：DisabledInPublish bool \json:"disabledInPublish"``；
    • API 侧从片段配置 JSON 中解析该字段，见 kernel/api/snippet.go：当 JSON 中存在disabledInPublish时读取其布尔值。
  • 集市插件包元数据：
    • 插件包 manifest 结构体中新增DisabledInPublish bool \json:"disabledInPublish"``，见 kernel/bazaar/package.go；
    • 插件模型同样持有该字段并标注“Whether disabled in publish mode”，见 kernel/model/plugin.go；
    • 解析入口为 kernel/bazaar/plugin.go 的ParseInstalledPlugin，它从已安装插件的元数据中读出disabledInPublish并与incompatible、disallowInstall、kernelIncompatible等状态一起返回。

使用含义：当你通过 SiYuan 的发布服务（Publish）把知识库发布为公开站点时，被标记disabledInPublish: true的代码片段与插件不会在发布站点中生效。这为“本地开发用、公开站点关闭”的差异化配置提供了声明式开关，而不是依赖删除/隐藏等隐式手段。

新增插件函数expandDocTree

v3.3.2 为插件体系新增了expandDocTree，用于在文件树中展开并定位到指定文档/笔记本节点，插件脚本可据此实现“跳转到某文档”“自动展开某文件夹路径”等导航类能力。

实现位于 app/src/plugin/API.ts，参数与行为如下：

参数类型说明
idstring笔记本 ID 或文档 ID
isSetCurrentboolean?是否把目标节点设为当前选中项，缺省为true

源码逻辑要点：

  1. 先通过window.siyuan.notebooks判断传入的id是否为笔记本（L288-L293）；
  2. 若为笔记本，直接取文件树中对应的b3-list节点；若不是笔记本，则调用内核接口/api/block/getBlockInfo反查该块所属的box（笔记本）与path，再通过文件树组件的selectItem定位到对应li节点（L303-L308）；
  3. isSetCurrent缺省视为true，调用file.setCurrent(liElement)选中该节点（L297-L315）；
  4. 最后找到折叠箭头.b3-list-item__arrow，若尚未展开（不含--open类名）则执行展开（L316-L319）——这就是函数名中 “expand” 的含义：确保目标节点在文件树中可见。

对插件作者而言，该函数把“按块 ID 反查文档位置并展开文件树”这一原本需要插件自行操作 DOM 的步骤收敛为标准 API，降低了导航类插件的实现成本。

内核 API 改进：appendBlock、insertBlock、prependBlock

变更记录中“改进内核 APIappendBlock、insertBlock和prependBlock”对应内核块操作接口 kernel/api/block_op.go。本次改进的核心是在插入前增加容器父块的合法性校验，防止通过 API 产生非法嵌套：

  • appendBlock（L551-L600）：参数为data、dataType、parentID。由于它只靠parentID定位插入位置，目标必须是容器块，因此先调用treenode.CheckContainerParent(parentID)校验，不合法直接返回错误（L566-L571）；
  • prependBlock（L656-L705）：同样只用parentID定位，执行了同样的容器校验（L671-L676）；
  • insertBlock（L761-L831）：支持parentID、previousID、nextID三个定位参数。只有当“仅靠parentID定位”（previousID与nextID均为空）时才要求父块必须是容器块（L792-L799）——若通过相邻块 ID 定位，则插入点落在块之间，父容器由上下文决定。

配套的批量版本batchAppendBlock、batchPrependBlock、batchInsertBlock采用相同的逐条校验逻辑，保证批量插入与单条插入语义一致。

此外，所有dataType为markdown的输入都会先经 Lute 引擎解析为块 DOM（dataBlockDOM），再进入appendInsert/prependInsert/insert事务；写入完成后统一通过model.PerformTransactions+FlushTxQueue落库，并用broadcastTransactions向其他客户端/视图广播变更。这一“事务 + 广播”的链路也正是多端同步与数据库/反链等实时更新的底层基础。

对插件与自动化脚本的提示：如果你的脚本通过这三个 API 往列表项、段落等非容器块上追加子块，升级后应留意返回的错误提示，改为选择合法的容器父块（文档、标题、折叠块、引用块等）。

修复缺陷

本版本共修复 6 个缺陷：

  • PDF 文件名过长无法生成标注图片：长文件名的 PDF 在生成文件标注图片时失败的问题；
  • 视频块网络地址不正确：视频块解析出的网络地址有误导致无法正常播放的问题；
  • 数据库日期字段无法粘贴 0 点时间：日期字段粘贴00:00时刻失效的问题，与上文日期字段筛选改进共同完善日期数据链路；
  • 预览模式下无法设置只读模式：文档处于预览模式时无法切换只读状态的问题；
  • 批量插入文件到编辑器时异常：与“拖入多个文件”的改进配套，修复批量文件插入流程的异常；
  • 部分输入法在块末尾粘贴链接后标点符号重复插入：特定输入法环境下粘贴块引用链接后，光标位置标点被重复上屏的问题。

小结与延伸阅读

v3.3.2 没有大特性，但每条改动都指向高频使用路径：数据库视图的筛选与分组、代码块与标题的块级操作、以及插件/发布生态的元数据能力。阅读路径建议：

  1. 变更清单：v3.3.2 中文变更记录、英文版；
  2. disabledInPublish实现：kernel/conf/snippet.go、kernel/bazaar/plugin.go、kernel/model/plugin.go、app/src/config/util/snippets.ts；
  3. expandDocTree实现：app/src/plugin/API.ts；
  4. 块操作 API 与容器校验：kernel/api/block_op.go（appendBlockL551、prependBlockL656、insertBlockL761）。

【免费下载链接】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），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/9/10 21:59:28

从零散灵感碎片到完整项目的重建方法论

1. 项目概述 作为一名从业多年的技术博主，我经常遇到一个困扰：当灵感突然来临时，却因为各种原因没能及时记录下完整的项目构思。这种情况在创意工作者和技术开发者中尤为常见——我们可能只来得及写下几个关键词或一个模糊的想法，…

作者头像 李华
网站建设 2026/9/10 21:55:22

PostgreSQL阻塞查询检测与优化实战

1. 为什么需要关注PostgreSQL阻塞查询 在数据库运维过程中，阻塞查询就像交通堵塞中的头车——它不仅自己无法前进，还会导致后方所有依赖它的查询陷入等待状态。我曾在生产环境遇到过一起典型的阻塞案例：一个简单的报表查询阻塞了整个业务系统…

作者头像 李华
网站建设 2026/9/10 21:54:57

Folo 移动端如何用 Expo 在 macOS 上搭建开发环境并跑通 iOS 模拟器

Folo 移动端如何用 Expo 在 macOS 上搭建开发环境并跑通 iOS 模拟器 【免费下载链接】follow 🧡 Folo is the AI RSS Reader 项目地址: https://gitcode.com/GitHub_Trending/fol/follow Folo 的移动端是一个基于 Expo 的 React Native 应用，代码…

作者头像 李华