SiYuan v3.4.0 更新解读：数据库看板视图正式发布与全端体验升级-育师

SiYuan v3.4.0 更新解读：数据库看板视图正式发布与全端体验升级

【免费下载链接】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.4.0 版本的官方变更日志（app/changelogs/v3.4.x/v3.4.0/v3.4.0_zh_CN.md）展开，聚焦本版本最具分量的新特性——数据库看板（Kanban）视图，并结合仓库源码深入讲解其数据结构与渲染机制；同时完整梳理本版本在数据库字段、导入导出、移动端、鸿蒙端、闪卡、剪藏、开发者 API 等方面的改进与缺陷修复。读完本文，你将掌握看板视图的底层实现原理、v3.4.0 各改进项的实际用法，以及如何基于源码定位这些功能的具体代码位置。

版本概述：数据库看板视图发布

v3.4.0 的核心亮点是数据库看板视图的正式发布。在此之前，SiYuan 的属性视图（数据库）已支持**表格视图（Table）与卡片视图（Gallery）**两种布局，v3.4.0 将看板视图作为第三种视图类型引入，让用户能够以"列 + 卡片"的形式按分组浏览与操作数据库记录，适合任务追踪、项目管理、状态流转等场景。

从源码结构看，属性视图的三种布局类型在内核中有明确定义（kernel/av/av.go）：

const ( LayoutTypeTable LayoutType = "table" // 属性视图类型 - 表格 LayoutTypeGallery LayoutType = "gallery" // 属性视图类型 - 卡片 LayoutTypeKanban LayoutType = "kanban" // 属性视图类型 - 看板 )

新建视图时，内核会根据布局类型初始化对应布局对象，其中看板视图的初始化入口为NewView()中的LayoutTypeKanban分支（kernel/av/av.go），调用NewLayoutKanban()完成默认配置。

看板视图的源码级解析

布局定义：LayoutKanban

看板视图的布局元数据定义在 kernel/av/layout_kanban.go，核心配置项包括：

配置项	类型	含义
`CoverFrom`	`CoverFrom`	卡片封面来源：0 无、1 内容图、2 资源字段
`CoverFromAssetKeyID`	`string`	资源字段 ID，仅在封面来源为资源字段时有效
`CardAspectRatio`	`CardAspectRatio`	卡片宽高比
`CardSize`	`CardSize`	卡片大小：0 小卡片、1 中卡片、2 大卡片
`FitImage`	`bool`	是否适应封面图片大小
`DisplayFieldName`	`bool`	是否显示字段名称
`FillColBackgroundColor`	`bool`	是否填充列背景颜色
`Fields`	`[]*ViewKanbanField`	看板中展示的字段列表

NewLayoutKanban()（kernel/av/layout_kanban.go）为新建看板视图设置了默认值：封面来源为内容图（CoverFromContentImage）、宽高比为16:9（CardAspectRatio16_9）、卡片大小为中卡片（CardSizeMedium）。这些默认值保证了开箱即用的视觉效果，用户可在界面中按需调整。

实例结构：Kanban 与 KanbanCard

当内核渲染看板视图时，会生成视图实例Kanban（kernel/av/layout_kanban.go），它继承BaseInstance，在布局配置的基础上补充了运行时数据：

Cards []*KanbanCard：当前看板的所有卡片；
CardCount int：总卡片数（用于前端分页加载判断）；
Fields []*KanbanField：实例化的字段列表。

每张卡片KanbanCard（kernel/av/layout_kanban.go）由以下部分组成：

ID：卡片 ID（即所绑定块的 ID）；
Values []*KanbanFieldValue：卡片上各字段的值；
CoverURL：卡片封面图超链接；
CoverContent：卡片封面文本内容（无图时使用）。

Kanban结构实现了Item接口所需的方法（GetItems、SetItems、CountItems、GetFields、GetValue等），这意味着看板视图与表格、卡片视图共用同一套属性视图操作框架，分组、筛选、排序、分页等能力天然复用。

渲染流程：RenderAttributeViewKanban

内核侧看板视图的渲染入口是RenderAttributeViewKanban（kernel/sql/av_kanban.go），整体流程如下：

缓存复用：若该视图已渲染过且未变更，直接返回缓存的*av.Kanban实例；
组装字段：遍历view.Kanban.Fields，通过attrView.GetKey(field.ID)解析字段定义；若字段已不存在，则在视图中删除（元数据查询场景不写盘）；
生成卡片：调用generateAttrViewItems生成卡片键值对，并过滤掉已被删除的卡片；
批量加载绑定块：收集卡片绑定的块 ID，通过filesys.LoadTrees(ialIDs)批量加载文档树，避免逐卡加载带来的性能损耗（kernel/sql/av_kanban.go）；
填充字段值：按字段 ID 建索引，将字段值与卡片对应；fillAttributeViewBaseValue负责格式化日期、数字、模板等字段的显示值；
渲染封面：fillAttributeViewKanbanCardCover（kernel/sql/av_kanban.go）根据CoverFrom取值：
- CoverFromContentImage：优先取文档标题图（title-img属性），否则遍历块内第一张图片；
- CoverFromAssetField：读取资源字段中的图片；
- CoverFromContentBlock：将块内容渲染为封面文本；
回填与收尾：批量获取块属性（BatchGetBlockAttrsWitTrees）、渲染自动生成字段（创建时间、更新时间、关联、汇总等），最后渲染模板字段——这样模板可以引用汇总、关联等自动生成的值；最后应用查询过滤filterByQuery与手动排序manualSort。

前端侧对应的渲染实现位于 app/src/protyle/render/av/kanban/render.ts，其中getKanbanTitleHTML负责渲染列标题（支持多选字段的彩色 chip、复选框图标、记录数统计），getKanbanHTML负责渲染卡片流与"加载更多"分页按钮，并支持虚拟滚动（virtualData），在卡片数量较多时只渲染可视区域内的卡片以保障性能。

使用方式

在 SiYuan 中新建或切换数据库视图时，通过视图工具栏将布局切换为"看板"，随后在视图设置中配置：

分组字段：看板按某个字段（如单选、多选、复选框）的值分组为列；
卡片字段：选择在卡片上展示的字段；
封面来源：内容图 / 资源字段 / 无；
卡片大小与宽高比：小 / 中 / 大卡片，16:9 等宽高比；
显示选项：是否显示字段名称、是否填充列背景颜色、是否适应封面图片大小。

这些配置均可在界面即时调整，并随数据库视图定义持久化保存，与表格、卡片视图共享同一套字段与数据体系。

数据库相关改进

"保存查询条件"支持保存"包含子文档"状态

此前在数据库中保存查询条件时，"包含子文档"这一搜索范围选项不会一并保存，导致每次重新打开视图都需要手动重新勾选。v3.4.0 修复了该问题，现在执行"保存查询条件"操作会完整记录"包含子文档"状态，查询条件跨会话保持一致。

创建时间 / 更新时间字段新增"具体时间"开关

数据库的"创建时间"与"更新时间"字段原本按日期粒度显示，v3.4.0 为这两个字段增加了"具体时间"（fillSpecificTime）开关，开启后字段值将精确到时分秒。

该开关的界面实现位于 app/src/protyle/render/av/col.ts：在字段设置菜单中渲染fillSpecificTime复选框，变更时通过事务接口setAttrViewColDateFillSpecificTime写入配置（app/src/protyle/render/av/col.ts）。渲染阶段，kernel/sql/av_kanban.go 中的fillAttributeViewBaseValue会读取field.Date.FillSpecificTime来决定日期值的格式化粒度，表格、卡片、看板三种视图均遵循该配置。

"添加到数据库"子列表显示视图名称

执行"添加到数据库"操作时，弹出的子列表现在会明确显示各视图的名称，便于在包含多个视图的数据库中准确选择目标视图，避免因视图重名或布局相近而误操作。

数据库同步需区分视图

v3.4.0 对数据库的同步逻辑进行了修正：此前多视图场景下同步可能互相干扰，现在同步过程按视图区分处理，确保各视图的布局配置、字段展示设置独立、正确地在多端之间同步。

模板字段的 HTML 内容渲染改进

数据库模板字段此前在渲染 HTML 内容时存在样式丢失或不完整的问题，本版本改进了模板字段的 HTML 内容渲染，使模板产出的富文本（如链接、加粗、列表等）能正确呈现在表格、卡片与看板视图中。

Markdown 与内容处理改进

导入 Markdown 后相对路径超链接转换为文档块引用

导入 Markdown 文件时，若文档内存在指向工作空间内其他文档的相对路径超链接，v3.4.0 会在导入过程中自动将其转换为文档块引用，使链接在导入后仍能正确跳转，而不是变成失效的相对路径。这一能力对使用"按相对路径互链"习惯编写的 Markdown 文档导入尤为重要。

Markdown 行级元素解析与超链接锚文本导出改进

行级元素解析（kernel/model/md2html.go 相关链路）：改善了 Markdown 行内元素的解析质量，覆盖加粗、斜体、行内代码、图片等行级结构的边界情况；
超链接锚文本导出：导出 Markdown 时，链接的锚文本（锚文本中的显示文字）处理更加准确，避免导出后锚文本丢失或错乱。

HTML 下划线样式剪藏改进

浏览器剪藏扩展在剪藏带有<u>下划线样式的 HTML 内容时，此前可能出现样式丢失或解析异常，v3.4.0 改进了该场景的剪藏效果，下划线样式可正确保留。

移动端与鸿蒙端改进

本版本对移动端与鸿蒙端投入了大量改进，主要包括：

改进移动端大纲面板：大纲的层级展示、滚动定位与折叠交互得到优化；
返回后光标位置丢失修复：在移动端编辑时从其他页面返回后，光标位置不再丢失，可继续在原文位置编辑；
改进移动端浏览器兼容性：提升在移动浏览器（含 Web 端使用场景）中的兼容性；
改进移动端打印边距：移动端打印时的页边距更合理；
支持鸿蒙端横屏模式：鸿蒙（HarmonyOS）端新增横屏支持；
改进鸿蒙端沉浸式体验：优化状态栏、导航栏与内容的沉浸式布局；
减小鸿蒙端应用体积：通过资源与依赖优化减小鸿蒙端安装包体积。

这些改进体现了 v3.4.0 对移动场景体验的系统性打磨。

交互与界面改进

支持设置状态栏消息开关：用户可在设置中控制状态栏是否显示消息通知，减少干扰；
改进闪卡删除交互：删除闪卡时的操作反馈更明确，误操作风险降低；
改进切换主题和更新代码片段后界面的加载：此前切换主题或更新代码片段后界面可能出现白屏、样式闪烁或加载缓慢，本版本优化了加载流程；
统一定位规则：对文档内定位（如跳转锚点、块定位）的规则进行了统一，减少不同入口定位行为不一致的问题；
反向链接与反向提及的排序模式持久化：反向链接面板与反向提及面板的排序方式选择现在会被记住，下次打开保持上次的选择；
改进虚拟引用关键字处理并支持换行：虚拟引用（((关键字))）的关键字匹配逻辑得到改进，并支持关键字内换行；
改进 YouTube IFrame 加载：嵌入 YouTube 视频时的加载体验更稳定；
支持设置将新创建的子文档放置在底部：文档树中新建子文档时，可选择将新文档追加到子节点列表末尾（默认插入到首个子节点之前）；
在侧边栏大纲中显示顶级标题计数：侧边栏大纲面板现在会显示顶级标题的数量，便于快速了解文档结构规模。

缺陷修复

v3.4.0 修复了以下主要缺陷：

复习闪卡时键盘快捷键失效：复习模式下快捷键无法触发翻面、评分等操作；
清理云端仓库失败：云端仓库清理（purge）流程在部分情况下失败；
图像 OCR 在某些情况下无法工作：OCR 功能在特定图片格式或环境下不生效；
在超级块内拖拽会触发异常状态：超级块内部拖拽导致块状态异常；
修改折叠和属性快捷键后出现错误提示：保存快捷键配置后错误弹窗；
拖放列表项导致一些错误：列表项拖拽排序后数据异常；
复制粘贴序号导致异常状态：复制带序号的列表内容后粘贴出现状态错乱；
属性面板中的汇总字段计算错误：汇总字段（rollup）在属性面板中的计算结果不准确。

这些修复覆盖了编辑、复习、同步、OCR 等多个核心链路。

平台与依赖变更

不再支持 macOS 11

自 v3.4.0 起，macOS 11（Big Sur）不再受支持。仍在 macOS 11 上使用 SiYuan 的用户需升级系统或停留在旧版本，新版本的系统要求以官方下载页说明为准。

升级至 Electron v38.7.0

桌面端内核重构升级至Electron v38.7.0（相关构建配置见 app/electron-builder.yml），随附更稳定的 Chromium 内核与安全修复。

开发者相关变更

插件卸载时执行 uninstall()

修复了插件在卸载时未执行uninstall()生命周期钩子的问题。现在卸载插件时，插件声明的uninstall()会被正确调用，便于插件作者在此清理资源、移除自定义事件监听等（插件生命周期相关实现见 kernel/plugin/manager.go）。

改进内核 API /api/storage/getRecentDocs

/api/storage/getRecentDocs接口（注册于 kernel/api/router.go）得到改进。其内核实现位于 kernel/api/storage.go：请求参数兼容旧版客户端（不强制要求sortBy字段），服务端根据sortBy对最近文档列表进行排序，并在只读/发布访问上下文中过滤无权限的文档（FilterRecentDocsByPublishAccess）。底层数据加载与排序逻辑位于 kernel/model/storage.go 与 kernel/model/storage.go，其中包含对失效最近文档的自动清理与持久化回写，确保接口返回始终有效的数据。

小结

v3.4.0 是 SiYuan 数据库能力的一次重要迭代：看板视图补齐了属性视图的第三种布局形态，其内核实现（kernel/av/layout_kanban.go、kernel/sql/av_kanban.go）与前端渲染（app/src/protyle/render/av/kanban/render.ts）共同构成了完整的数据链路。与此同时，本版本在数据库字段细化（"具体时间"开关）、Markdown 导入导出、移动端与鸿蒙端体验、插件生命周期、内核 API 等方面均有实质性改进。若需了解各变更的完整设计背景，可结合 kernel/av 目录与 kernel/api 目录中的源码进一步研读；完整变更列表见 app/changelogs/v3.4.x/v3.4.0/v3.4.0_zh_CN.md。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

SiYuan v3.4.0 更新解读：数据库看板视图正式发布与全端体验升级