SiYuan v3.2.0 发布解析：数据库画廊视图上线与内核 API 扩展

导读：本文以 SiYuan（思源笔记）v3.2.0 版本变更记录（v3.2.0_zh_CN.md）为核心骨架，深入解读该版本的主打特性「数据库画廊视图」，并结合仓库源码剖析其底层数据模型、数据库相关增强、导出/移动端改进、安全修复与内核 API 扩展。读完本文，你将掌握 v3.2.0 的完整变更清单、画廊视图的字段配置原理，以及两个新内核 API 的调用方式与适用场景。

一、版本概览：数据库画廊视图正式发布

v3.2.0 是思源笔记数据库能力的一个重要里程碑，官方概述只有一句话：数据库画廊视图现已发布（Database gallery view now available!）。

在此之前，思源数据库（属性视图）已经支持表格（table）、看板（kanban）等布局；本版本新增的「卡片」（gallery）布局，让用户可以像浏览卡片墙一样查看数据库记录，配合封面图、卡片字段自定义与宽高比设置，适合图片集、灵感墙、书影音收藏等场景。

围绕这个核心特性，v3.2.0 还包含约 30 项改进、4 项缺陷修复、3 项依赖重构和 2 项内核 API 扩展，并完全移除了 Google Analytics，进一步强化隐私优先定位。

二、核心特性深度解析：数据库画廊（卡片）视图

2.1 视图类型注册

在源码层面，画廊视图被注册为数据库的第四种布局类型。在 kernel/av/av.go 中可以找到：

LayoutTypeGallery LayoutType = "gallery" // 属性视图类型 - 卡片

创建新数据库实例时，默认布局类型同样指向 LayoutTypeGallery，且各布局切换逻辑（kernel/av/layout.go）均对 LayoutTypeGallery 做了分支处理，说明画廊视图与表格、看板等布局处于同一套布局框架内，可随时切换而不丢失数据。

2.2 画廊布局的配置结构

画廊视图的布局配置定义在 kernel/av/layout_gallery.go，这是理解该视图全部可调选项的最佳入口：

type LayoutGallery struct {
	*BaseLayout

	CoverFrom           CoverFrom       `json:"coverFrom"`                     // 封面来源，0：无，1：内容图，2：资源字段
	CoverFromAssetKeyID string          `json:"coverFromAssetKeyID,omitempty"` // 资源字段 ID，CoverFrom 为 2 时有效
	CardAspectRatio     CardAspectRatio `json:"cardAspectRatio"`               // 卡片宽高比
	CardSize            CardSize        `json:"cardSize"`                      // 卡片大小，0：小卡片，1：中卡片，2：大卡片
	FitImage            bool            `json:"fitImage"`                      // 是否适应封面图片大小
	DisplayFieldName    bool            `json:"displayFieldName"`              // 是否显示字段名称

	CardFields []*ViewGalleryCardField `json:"fields"` // 卡片字段
}

关键配置项说明：

配置项	类型	取值与含义
CoverFrom	枚举	卡片封面来源：CoverFromNone（无封面）、CoverFromContentImage（内容图）、CoverFromAssetField（资源字段）、CoverFromContentBlock（内容块）
CoverFromAssetKeyID	字符串	当封面来源为资源字段时的字段 ID
CardAspectRatio	枚举	卡片宽高比：16:9、9:16、4:3、3:4、3:2、2:3、1:1（默认 16:9）
CardSize	枚举	卡片大小：小、中、大（默认中卡片）
FitImage	布尔	封面图片是否按卡片自适应
DisplayFieldName	布尔	卡片上是否显示字段名称

新建画廊布局时的默认值（kernel/av/layout_gallery.go）为：封面来源取内容图、宽高比 16:9、中等卡片，并默认开启图标显示（ShowIcon: true）。

2.3 画廊实例的运行期结构

当数据库以画廊布局渲染时，运行期实例由 kernel/av/layout_gallery.go 中的 Gallery 结构描述：

type Gallery struct {
	*BaseInstance

	CoverFrom           CoverFrom       `json:"coverFrom"`
	CoverFromAssetKeyID string          `json:"coverFromAssetKeyID,omitempty"`
	CardAspectRatio     CardAspectRatio `json:"cardAspectRatio"`
	CardSize            CardSize        `json:"cardSize"`
	FitImage            bool            `json:"fitImage"`
	DisplayFieldName    bool            `json:"displayFieldName"`
	Fields              []*GalleryField `json:"fields"`  // 卡片字段
	Cards               []*GalleryCard  `json:"cards"`   // 卡片
	CardCount           int             `json:"cardCount"` // 总卡片数
}

每张卡片 GalleryCard 携带自身 ID、字段值列表，以及由布局计算出的封面信息 CoverURL（封面图片链接）与 CoverContent（封面文本内容）。后端通过 GetValue(itemID, keyID)、GetBlockValue() 等方法按卡片 ID 与字段 ID 快速取值，这也印证了 v3.2.0「改进数据库加载性能」的实现基础——卡片渲染所需的封面、字段值都在一次实例加载中完成聚合，前端无需逐卡请求。

2.4 前端使用入口

• 打开任意数据库块，点击左上角布局切换按钮，选择「卡片」布局；
• 在卡片视图右上角菜单中配置：封面来源（内容图/资源字段/无）、卡片宽高比、卡片大小、是否适应封面图片、是否显示字段名称；
• 拖拽卡片可进行自定义排序，卡片点击进入对应记录（块）详情。

三、数据库专项增强：本版本的第二主旋律

v3.2.0 围绕数据库做了密集改进，与其「画廊视图上线」形成完整配套：

1. 数据库支持设置显示字段图标：每个字段可在表头/卡片上显示自定义图标，增强数据库的可视化辨识度；
2. 数据库支持设置字段换行：单元格内容可按字段级配置自动换行，避免长文本被截断，改善表格可读性；
3. 同一视图的不同布局使用相同的过滤、排序、分页和自定义排序规则：这是画廊视图体验的关键保障——用户在表格中设置的过滤/排序条件，切换到卡片或看板布局后仍然生效，各布局共享一套查询状态，不会因切换布局而丢失筛选结果；
4. 改进数据库加载性能：从实例结构（封面、卡片字段一次聚合）与查询路径上降低渲染开销；
5. 数据库索引内容/Markdown 值不再包含零宽空格：修复了索引数据中混入不可见字符导致搜索匹配异常的问题，保证数据库全文检索结果干净可靠；
6. 在数据库块菜单中添加「复制数据库 ID」：方便插件开发者与高级用户拿到数据库块的 ID，用于 API 调用或块引用定位。

这些改进共同服务于一个目标：让数据库从「结构化表格」进化为「可多形态展示的内容管理面板」。

四、编辑器、导出与网页剪藏改进

4.1 编辑器交互

• 改进多选块（multi-select block）的选中与操作体验；
• 按住 Shift 时无法拖动列表项的点——修复按住 Shift 状态下列表项拖拽点被误触的问题；
• 无法从 .protyle-action 元素开始选择——修复从块操作按钮区域无法起始选区的问题；
• 在非空块中粘贴 /^\s*>|\*|-|\+|\d*.|\[ \]|[x] 不进行转换——该正则匹配的是 Markdown 列表/引用/复选框标记，之前粘贴这类内容到非空块会被误转成列表，本版本仅保留在空块中的自动转换行为；
• 改进自定义块字体大小后列表、代码块和标题的比例——块级自定义字体大小现在会同步影响列表项、代码块与标题的缩放比例；
• 将文档转换为标题时移除 title 属性——避免转换后残留旧标题属性；
• 改进超链接/图片标题的转义——链接与图片的 title 文本在渲染与导出时转义更规范。

4.2 导出相关

• 改进表格导出的对齐方式；
• 改进带子文档的空文档导出，且导出合并子文档时忽略最后一个空段落块——避免合并导出时在末尾产生多余空行；
• 导出预览中无法复制图片——修复导出预览窗口图片无法复制的缺陷；
• 改进粘贴到微信公众号——优化了复制到微信公众号编辑器时的粘贴格式。

4.3 网页剪藏

• 改进 HTML 公式剪藏：网页中的公式（MathML/KaTeX 等）剪藏进思源后能正确渲染；
• 改进 HTML 表格剪藏：网页表格剪藏后的结构与对齐更准确；
• 支持剪藏网页后打开文档：剪藏完成后可直接跳转到刚生成的文档，方便立即校对。

五、移动端与登录体验

• 移动设备上公式左右滑动不再打开侧边栏：修复在公式区域横向滑动误触侧边栏的问题；
• 移动设备上的块引用弹窗会被键盘遮挡：弹窗改为随键盘上移，不再被软键盘遮住；
• Android 上点击工具栏 + 后关闭键盘：工具栏展开后自动收起软键盘，避免遮挡内容区；
• Android 工具栏内容无法滑动：工具栏在窄屏下可横向滚动；
• Android 检查 WebView 版本 95+：启动时检测系统 WebView 版本，低于 95 时给出升级提示，保证渲染兼容性；
• 登录时添加「记住我」复选框以保存会话：勾选后登录状态可持久化保存，减少重复登录。

六、安全与隐私：彻底移除 Google Analytics

v3.2.0 在「移除功能（Abolishment）」分类下唯一一项是完全移除 Google Analytics。这与此前版本逐步剥离第三方统计的行为一脉相承，结合项目「开源、隐私优先、自托管」的定位，移除遥测意味着自托管部署下用户行为数据完全留在本地，不会外发至第三方分析服务。

此外，本版本修复了一个真实的安全漏洞：自定义 Emoji 文件名导致的 XSS 漏洞。由于自定义 emoji 以文件形式存放并可通过名称注入脚本，攻击者可构造恶意 emoji 名称触发跨站脚本执行；本版本对 emoji 名称的解析做了安全处理。

七、依赖重构与平台升级

• 升级至 Electron v37.2.0：桌面端（Windows/macOS/Linux）底层运行时升级，涉及 Chromium 与 Node.js 版本整体提升（对应仓库中的 electron-builder.yml 等打包配置）；
• 升级 abcjs 6.2.2 至 6.5.0：乐谱渲染能力升级；
• 升级 visjs 9.1.2 至 9.1.13：关系图/网络图渲染库升级。

这些重构均属于「内部换引擎、外部保接口」的兼容性升级，不会改变用户操作习惯。

八、开发者：两个新增内核 API

8.1 /api/block/getBlockDOMs

新增内核 API，用于批量获取指定块的渲染 DOM。其实现位于 kernel/api/block.go，请求参数为块 ID 数组 ids：

POST /api/block/getBlockDOMs
{
  "ids": ["20210808180117-6v0mkxr", "20240113110040-7sgw8kl"]
}

实现要点：

• 支持加密笔记本场景：通过 encryptedNotebookFromArg 解析加密笔记本上下文后调用 model.GetBlockDOMsInBox；
• 在只读角色（发布/只读上下文）下，会依据发布访问控制过滤 DOM，未授权块不会返回内容；
• 路由注册在 kernel/api/router.go，需要管理员角色（CheckAdminRole）。

配套接口 /api/block/getBlockDOMsWithEmbed（kernel/api/router.go）额外支持展开嵌入块内容，适合需要完整渲染内容的场景。

8.2 /api/export/exportMdContent 新增 fillCSSVar 参数

Markdown 导出接口 exportMdContent 新增布尔参数 fillCSSVar。解析逻辑见 kernel/api/lute.go：

fillCSSVar := false
if nil != arg["fillCSSVar"] {
	fillCSSVar = arg["fillCSSVar"].(bool)
}
markdownContent := model.ExportStdMarkdown(id, assetsDestSpace2Underscore, fillCSSVar, adjustHeadingLevel, imgTag)

该参数控制导出 Markdown 中内联的 HTML 样式是否使用已填充的 CSS 变量值。当导出内容包含 HTML 片段且这些片段引用了 CSS 变量时：

• fillCSSVar: true：导出前将 CSS 变量替换为实际计算值（实现见 kernel/model/export.go），导出的 HTML 在任意渲染环境中样式一致；
• fillCSSVar: false（默认）：保留 CSS 变量写法，适合在仍运行思源主题的环境中使用。

导出预览接口 /api/export/exportPreview 默认即使用 fillCSSVar: true（kernel/api/export.go），以保证预览与最终导出效果一致。该参数对于「把带样式的文档迁移到其他 Markdown 渲染器」的自动化流程尤其有用。

九、结语

v3.2.0 是一次「数据库体验重塑 + 隐私收口 + 开发者基建补强」的版本：画廊视图让数据库从表格/看板扩展到卡片形态，并通过共享过滤排序规则与加载性能优化让多布局切换成为日常可用的工作流；同时彻底移除 Google Analytics、修复 emoji XSS，兑现了隐私优先的承诺；而 getBlockDOMs 与 fillCSSVar 两个内核 API 为插件生态与自动化导出打开了新的集成空间。

如果你正准备基于思源数据库构建图片资料库、影音收藏墙或轻量 CRM，画廊视图加上字段图标与换行设置，就是 v3.2.0 给你的开箱即用答案。