SiYuan v3.2.0 深度解读：数据库画廊视图发布与内核 API 增强

导读：本文以 SiYuan（思源笔记）v3.2.0 官方中文更新日志为主体，结合仓库源码深入解读本次版本的核心变化。你将了解新发布的数据库画廊视图的完整配置项与默认行为、/api/block/getBlockDOMs 批量块 DOM 渲染接口的底层实现、/api/export/exportMdContent 新增的 fillCSSVar 参数，以及本版本在剪藏、导出、移动端与安全方面的一系列改进，可直接对照源码文件进行验证与二次开发。

版本定位与概览

v3.2.0 是 SiYuan 在数据库（属性视图）能力上的一次重要迭代，其标志性特性是数据库画廊视图的正式发布。围绕这一核心特性，版本还包含大量针对数据库、剪藏、导出、移动端体验的改进，一项隐私相关的功能移除（完全移除 Google Analytics），以及两项面向开发者开放的内核 API 增强。

本次版本的完整变更记录文件位于 app/changelogs/v3.2.x/v3.2.0/v3.2.0_zh_CN.md，同目录下还提供英文与繁体中文版本（v3.2.0.md、v3.2.0.zh-TW.md）。

引入特性：数据库画廊视图

功能背景

在 v3.2.0 之前，SiYuan 的数据库已经支持表格视图与看板视图。画廊视图（Gallery）以卡片流的形式展示数据库记录，适合图片素材库、书影音清单、作品集等以视觉内容为主的场景，是数据库多视图体系的重要补充。

前端渲染与布局类型

画廊视图在前端由 app/src/protyle/render/av/gallery/render.ts 及其目录下的 item.ts、util.ts 负责渲染，与看板视图（app/src/protyle/render/av/kanban/render.ts）共用同一套属性视图基础设施（app/src/protyle/render/av/layout.ts）。

在 kernel/av/layout_gallery.go 中，画廊视图在底层被建模为独立的布局类型：

// LayoutGallery 描述了卡片布局的结构。
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"` // 卡片字段
	// ...
}

内核中通过 kernel/av/av.go 的 NewGalleryView() 创建默认画廊视图，其初始布局使用 NewLayoutGallery()，默认配置为：封面来源为内容图（CoverFromContentImage）、卡片宽高比为 16:9、卡片大小为中等（CardSizeMedium）。

卡片封面来源（CoverFrom）

卡片封面可取自四种来源（见 kernel/av/layout_gallery.go 中的枚举定义）：

枚举值	说明
CoverFromNone	无封面
CoverFromContentImage	内容图（默认），从卡片主块内容中提取图片
CoverFromAssetField	资源字段，需要配合 CoverFromAssetKeyID 指定具体资源字段
CoverFromContentBlock	内容块

卡片宽高比（CardAspectRatio）

支持 7 种宽高比（kernel/av/layout_gallery.go）：

枚举值	比例
CardAspectRatio16_9	16:9（默认）
CardAspectRatio9_16	9:16
CardAspectRatio4_3	4:3
CardAspectRatio3_4	3:4
CardAspectRatio3_2	3:2
CardAspectRatio2_3	2:3
CardAspectRatio1_1	1:1

卡片大小（CardSize）

枚举值	说明
CardSizeSmall	小卡片
CardSizeMedium	中卡片（默认）
CardSizeLarge	大卡片

与其他布局的联动规则

本版本同时实现了一个重要的数据库行为统一：同一视图的不同布局共享相同的过滤、排序、分页和自定义排序规则（对应 issue #15197）。这意味着用户可以在表格、看板、画廊三种布局间自由切换，而无需重新配置查询条件，视图的状态语义在各布局间保持一致。

从源码看，这一设计在数据结构上即有所体现：kernel/av/av.go 中 NewGalleryView() 创建的 View 结构自带 Filters、Sorts、PageSize 字段，这些字段属于视图（View）层面而非布局（Layout）层面；而画廊布局只管理卡片相关的展示属性（封面、比例、大小等）。此外，kernel/av/av_fix.go 中还有将 view.table.rowIds 或 view.gallery.cardIds 统一复制到 view.itemIds 的兼容处理逻辑，进一步印证了视图层面统一管理条目顺序的设计。

数据库相关改进

v3.2.0 在数据库上还有多项细节增强，均围绕可用性展开：

• 数据库支持设置显示字段图标（#15089）：字段图标可用于快速识别字段类型。
• 数据库支持设置字段换行（#15181）：长文本字段可配置自动换行，避免内容被截断。
• 数据库块菜单中新增"复制数据库 ID"（#15036）：便于插件开发或跨块引用时快速获取数据库块 ID。
• 改进数据库加载性能（#15115）：大数据量视图的加载体验得到优化。
• 数据库索引内容/Markdown 值不再包含零宽空格（#15204）：零宽空格此前可能干扰检索与外部系统集成，移除后索引更干净、可匹配性更强。

这些改进配合新发布的画廊视图，共同提升了数据库作为知识管理核心组件的完整度。

开发者 API 增强

新增内核 API：/api/block/getBlockDOMs

该接口用于批量获取多个块的 DOM 字符串。与单块接口 getBlockDOM 相比，它支持一次请求传入多个块 ID，减少往返开销。

路由注册位于 kernel/api/router.go：

ginServer.Handle("POST", "/api/block/getBlockDOMs", model.CheckAuth, model.CheckAdminRole, getBlockDOMs)
ginServer.Handle("POST", "/api/block/getBlockDOMsWithEmbed", model.CheckAuth, model.CheckAdminRole, getBlockDOMsWithEmbed)

实现位于 kernel/api/block.go。请求参数为 ids（字符串数组）；底层由 kernel/model/block.go 的 GetBlockDOMsInBox 完成渲染：对每个块 ID，先加载其所属文档树，再定位节点，通过 luteEngine.RenderNodeBlockDOM(node) 将单个块渲染为 DOM 字符串，最后以 map[id]dom 的形式返回。注意 GetBlockDOMsInBox 的注释明确要求：未指定 boxID 时禁止遍历加密笔记本，涉及加密笔记本时需通过 notebook 参数显式传入笔记本 ID。

发布模式下（只读角色上下文），接口还会调用 filterBlockDOMsByPublishAccess 按发布访问权限过滤无权访问的块（kernel/api/block.go），与发布访问控制策略保持一致。

增强内核 API：/api/export/exportMdContent 新增 fillCSSVar 参数

Markdown 导出接口 exportMdContent 新增布尔参数 fillCSSVar（默认 false），用于控制导出内容中是否填充 CSS 变量（CSS Variables）。实现见 kernel/api/export.go，参数通过 util.BindJsonArg("fillCSSVar", &fillCSSVar, false, false) 解析，最终传入 model.ExportMarkdownContent(id, refMode, embedMode, yfm, fillCSSVar, adjustHeadingLevel, imgTag, addTitle)。

该参数的实际价值在于：导出的 Markdown 若在后续被渲染为 HTML，fillCSSVar 可决定是否将主题中的 CSS 变量展开为具体色值，避免导出文档在脱离 SiYuan 主题环境后出现样式变量无法解析的问题。同一逻辑也用于导出预览（kernel/api/export.go 中 ExportPreview 的 fillCSSVar 推导）。

剪藏与导出改进

本版本围绕"外部内容进入、内部内容输出"两条链路做了大量打磨：

• 支持剪藏网页后打开文档（#15051）：剪藏完成后可直接定位到新生成的文档。
• 改进 HTML 公式剪藏（#15109）与 HTML 表格剪藏（#15131）：提升网页剪藏时复杂公式与表格的结构还原质量。
• 改进超链接/图片标题的转义（#15023）：避免特殊字符在导出/复制时被错误处理。
• 改进表格导出的对齐方式（#14990）。
• 改进带子文档的空文档导出（#15009），并在导出合并子文档时忽略最后一个空段落块（#15028），减少冗余空行。
• 将文档转换为标题时移除 title 属性（#15019）。
• 改进粘贴到微信公众号（#15138）：优化公众号编辑器场景下的粘贴排版。
• 导出预览无法复制图片（#15152）得到修复。

移动端与输入交互改进

• Android 检查 WebView 版本 95+（#15147）：低于该版本将无法获得完整功能支持，官方对运行环境提出了明确门槛。
• 在 Android 上点击工具栏 + 后关闭键盘（#14969），避免键盘遮挡编辑区域。
• Android 上工具栏内容无法滑动（#14979）得到修复。
• 移动设备上的块引用弹窗会被键盘遮挡（#14936）得到修复。
• 在移动设备上公式左右滑动不再打开侧边栏（#14682）：手势冲突问题解决。
• 按住 Shift 时无法拖动列表项的点（#14835）得到修复。

编辑器与其他界面改进

• 改进多选块（#14012）：多选块的选择与操作体验增强。
• 改进块图标显示（#14832）。
• 在非空块中粘贴 /^\s*>|\*|-|\+|\\d*.|\[ \]|[x] 不进行转换（#14965）：非空块中粘贴匹配列表语法的文本时不再被自动转换为列表，避免误转换。
• 改进自定义块字体大小后列表、代码块和标题的比例（#14984）：字体缩放后各块类型的相对尺寸更协调。
• 无法从 .protyle-action 元素开始选择（#14997）得到修复。
• 动态图标不再显示网络图片角标（#15140）。
• 如果不存在笔记本，隐藏"已关闭笔记本"元素（#14982）：空状态下界面更整洁。
• 登录时添加"记住我"复选框以保存会话（#14964）：会话保持能力增强。
• 改进搜索设置（#15166）。
• 访问认证失败时刷新页面跳转到认证页面（#15163）：认证流程更顺畅。

移除功能与安全修复

完全移除 Google Analytics

v3.2.0 完全移除了 Google Analytics（#15096）。这与 SiYuan"开源、隐私优先、自托管"的产品定位一致——移除第三方分析后，数据不再向任何外部统计服务发送，进一步强化隐私承诺。

安全修复：自定义 Emoji 文件导致的 XSS 漏洞

本版本修复了一个由自定义 Emoji 文件引发的跨站脚本（XSS）漏洞（#15034）。由于自定义 Emoji 可被用户导入并展示在文档中，若文件内容未经过滤，可能注入恶意脚本。此修复提示使用自定义 Emoji 时应注意来源可信度，也体现了项目在输入安全上的持续投入。

依赖与运行时升级

• 升级 Electron 至 v37.2.0（#15022）：桌面端运行时升级，带来 Chromium/Node.js 底层能力与安全更新。
• 升级 abcjs 6.2.2 至 6.5.0（#14989）：乐谱渲染能力升级。
• 升级 visjs 9.1.2 至 9.1.13（#15170）：图形/网络可视化库升级。

新语言支持

• 添加葡萄牙语巴西语支持（#15029）：界面语言新增 pt-BR。对应语言文件位于 app/appearance/langs/pt-BR.json。

小结与升级建议

v3.2.0 的核心价值可以概括为三点：

1. 数据库可视化能力补全：画廊视图与表格、看板并列，配合共享过滤/排序规则、字段图标、字段换行等改进，数据库在多布局场景下更加顺手；
2. 开发者生态扩展：/api/block/getBlockDOMs 为插件与集成场景提供批量 DOM 渲染能力，exportMdContent 的 fillCSSVar 参数让导出管线更可控；
3. 隐私与稳定性加固：完全移除 Google Analytics、修复 Emoji XSS 漏洞，并完成 Electron 37 等基础依赖升级。

对于使用数据库管理素材或内容库的用户，建议升级后重点体验画廊视图的封面来源与卡片比例配置；对于插件开发者，则可基于 getBlockDOMs 批量接口重构依赖逐块请求 DOM 的逻辑。若需对照英文或繁体中文版本阅读，可查看同目录下的 v3.2.0.md 与 v3.2.0.zh-TW.md。