SiYuan v3.1.14 版本深度解析数据库计算增强、编辑器交互打磨与数据同步性能优化【免费下载链接】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.1.14 的官方变更记录v3.1.14_zh_CN.md系统梳理该版本在数据库属性视图、编辑器与文档树交互、导入导出、搜索闪卡、同步性能、依赖升级以及开发者 API 等方面的全部改动。读完本文你将全面掌握 v3.1.14 的功能增量、背后对应的内核源码实现位置以及面向插件开发者的新 API 能力可直接对照仓库代码进一步深挖。版本概览一次以细节与性能为主题的迭代v3.1.14 是一个典型的细节打磨型版本官方概述只有一句话——此版本改进了大量细节优化了数据同步性能但展开后的变更记录覆盖了30 项功能改进、3 项缺陷修复、4 项依赖升级和 4 项开发者能力更新。从整体脉络看该版本集中发力在以下几个方向数据库属性视图能力补全关系字段直接建新条目、唯一值百分比计算、资源文件拖拽入字段编辑器与文档树交互重构拖拽语义调整、块位置保持、快捷键覆盖文档资产管理图片 / IFrame 延迟加载、导入导出行为改进稳定性与性能数据同步性能优化、反向链接高亮修复、撤销异常修复开发者生态/api/block/getBlockKramdown扩展、插件工具栏热键支持、内置 CalDAV 服务。一、数据库属性视图功能增强v3.1.14 在数据库领域带来了三项值得关注的新能力其核心计算逻辑与 UI 层改动分别落在 kernel/av/ 与 app/src/protyle/render/av/ 目录。1.1 填写数据库关系字段时可直接创建新条目此前在数据库的关系Relation字段中填写内容时只能选择已存在的条目v3.1.14 起支持在填写关系字段的过程中直接创建新条目issue #10914。这一改动打通了从主表引用到目标表的创建闭环避免用户先在目标表中新建记录再回来引用的繁琐路径。1.2 计算字段新增唯一值百分比Percent unique values这是本版本数据库计算能力的核心增量issue #13192。在原有的Count unique values唯一值计数基础上新增了Percent unique values唯一值百分比算子其含义为去重后的唯一值数量 ÷ 行数。从内核源码可以确认该算子的完整定义与实现。在 kernel/av/calc.go 中定义了全部计算算子枚举const ( CalcOperatorNone CalcOperator CalcOperatorUniqueValues CalcOperator Unique values CalcOperatorCountAll CalcOperator Count all CalcOperatorCountValues CalcOperator Count values CalcOperatorCountUniqueValues CalcOperator Count unique values CalcOperatorCountEmpty CalcOperator Count empty CalcOperatorCountNotEmpty CalcOperator Count not empty CalcOperatorPercentEmpty CalcOperator Percent empty CalcOperatorPercentNotEmpty CalcOperator Percent not empty CalcOperatorPercentUniqueValues CalcOperator Percent unique values // ... )而在关系字段的专项计算函数calcFieldRelationkernel/av/calc.go中Percent unique values的实现是先借助map[string]bool对关系引用的BlockIDs去重计数再除以条目总数并以百分比数字格式输出case CalcOperatorPercentUniqueValues: countUniqueValues : 0 uniqueValues : map[string]bool{} for _, item : range collection.GetItems() { values : item.GetValues() if nil ! values[fieldIndex] nil ! values[fieldIndex].Relation { for _, id : range values[fieldIndex].Relation.BlockIDs { if !uniqueValues[id] { uniqueValues[id] true countUniqueValues } } } } if 0 len(collection.GetItems()) { calc.Result Value{Number: NewFormattedValueNumber(float64(countUniqueValues)/float64(len(collection.GetItems())), NumberFormatPercent)} }类似的去重计数逻辑在文本、多选、数字、日期、URL、Email、Phone、关联块、创建/更新时间、汇总字段等各类型字段的统计中均有覆盖kernel/av/calc.go 全文件说明唯一值类统计是属性视图计算体系中的通用基础能力。NumberFormatPercent百分比格式化常量定义于 kernel/av/value.go。1.3 资源文件可直接拖入数据库与属性面板的资源字段此前将图片、PDF 等资源放进数据库的资源Asset字段只能通过字段选择器操作v3.1.14 支持将资源文件直接拖拽到数据库表格单元格和属性面板的资源字段中issue #12904显著降低素材管理成本。这一交互在渲染层由 app/src/protyle/render/av/cell.ts 与 app/src/protyle/render/av/blockAttr.ts 承载。1.4 属性面板样式与数据库相关体验微调改进数据库属性面板样式PR #13248优化了属性面板中字段展示与编辑的视觉细节改进拖动块到数据库的高亮PR #13284当把一个普通块拖入数据库行时目标位置的落点提示更明确拖动块高亮改进PR #13281编辑器内拖拽块时的拖放预览反馈更清晰。二、编辑器与文档树交互改进本版本在文档树与编辑器交互上做了大量手感层面的调整。2.1 文档树拖拽语义调整拖动与 Alt拖动互换v3.1.14 交换了文档树上的拖动与Alt拖动行为issue #13181。调整后普通拖动默认执行移动块到新位置Alt拖动执行复制。同时改进了将标题或列表项拖动到文档树时的行为issue #13170并针对拖动块到文档树/数据库的落点高亮做了优化PR #13281、PR #13284让拖放目标更可预期。2.2 文档树复制支持快捷键文档树上的复制操作现在可以直接通过快捷键触发issue #13128配合快捷键面板 app/src/config/tabs/keymapUi.ts 可完成自定义映射无需每次右键菜单操作。2.3 编辑器宽度与块位置保持调整编辑器宽度后保持块位置issue #13127在窗口宽度变化、左右分栏调整后当前编辑光标所在块尽量保持在可视区域内不再漂移改进水平布局的间距和宽度issue #12318适配横向排版的间距与宽度计算改进图片宽度设置issue #12516图片宽度调整的交互与精度优化改进子列表的换行行为issue #13016当子列表内同时包含列表块与普通块时的换行渲染更符合预期改进撤销后的光标位置issue #13244撤销操作完成后光标回到更合理的落点。2.4 块统计与多选复制添加选中块和总块的统计issue #13235在编辑器中选中内容时可查看选中块数量与文档总块数便于把握文档结构规模右键菜单支持对多个选中文档或块进行更多复制选项issue #11561多选场景下的复制能力扩展改进全选后粘贴和复制代码块PR #13271修复全选复制代码块的格式问题。三、搜索、闪卡、文件历史与行级查找替换3.1 搜索与反向链接高亮改进搜索高亮issue #13178搜索结果中关键词的高亮标记渲染优化修复反向链接关键词高亮不正确issue #13210见缺陷修复反向链接面板Backlink中关键词高亮错位的问题得到解决。3.2 闪卡细节对于没有创建填空卡片的闪卡块取消显示答案入口issue #13163此前某些闪卡块因未生成填空卡片点击显示答案无实际内容v3.1.14 起这类块的显示答案操作会被隐藏避免无效交互。该逻辑与闪卡Riff卡片面板相关卡片类型分发在 app/src/card/newCardTab.ts 中体现all/doc/notebook三种范围。3.3 文件历史与行级查找替换改进文件历史界面issue #13193历史版本对比与恢复的界面细节优化改进行级元素查找替换issue #13200对行级元素加粗、斜体、链接等进行查找替换时匹配范围与替换结果更精确。四、导入导出改进导入导出是 v3.1.14 改动较密集的领域共涉及 6 项改动项说明改进导入 Markdown#13245Markdown 导入的块解析与还原更准确改进导出 Markdown#13273导出时 Markdown 标记的生成质量提升改进导出块引用#13283导出包含块引用的文档时引用格式更规范改进 HTML 剪藏#13270网页剪藏为 Markdown/文档时的转换细节优化导出文件名中的特殊字符替换为_#13274导出文件名的跨平台合法性保证改进全选后粘贴和复制代码块PR #13271代码块全选复制与粘贴的格式一致性其中导出文件名中的特殊字符替换为_与内核工具函数FilterFileName直接对应。在 kernel/util/file.go 中该函数对文件名中的反斜杠、正斜杠、冒号、星号、问号、双引号、单引号、尖括号、竖线等非法字符逐一替换为下划线并进一步调用RemoveInvalid清除不可见字符func FilterFileName(name string) string { name strings.ReplaceAll(name, \\, _) name strings.ReplaceAll(name, /, _) name strings.ReplaceAll(name, :, _) name strings.ReplaceAll(name, *, _) name strings.ReplaceAll(name, ?, _) name strings.ReplaceAll(name, \, _) name strings.ReplaceAll(name, , _) name strings.ReplaceAll(name, , _) name strings.ReplaceAll(name, , _) name strings.ReplaceAll(name, |, _) name RemoveInvalid(name) // Remove invisible characters from file names when uploading assets name strings.TrimSpace(name) // ... }在 kernel/model/export.go 中FilterFileName被广泛用于导出 PDF、HTML、Word、Markdown 及 zip 压缩包的文件命名如第 1085、1291 行注释所示此前曾因未过滤非法字符导致导出失败。v3.1.14 将此行为统一收口到导出文件名层面进一步规避了 Windows 等文件系统上的命名冲突。五、性能与稳定性延迟加载与数据同步优化5.1 图片和 IFrame 使用延迟加载图片和 IFrame 使用延迟加载issue #13204是本次性能优化的重头戏编辑器文档中距离视口较远的图片与内嵌 IFrame 不再一次性全部加载而是在滚动接近时按需加载显著降低大文档的初始渲染开销。从渲染层源码可以看到该能力的落地痕迹数据库资源字段的图片渲染已普遍使用原生loadinglazy属性如 app/src/protyle/render/av/cell.ts 中的img loadinglazy ...画廊/看板视图封面图同样使用loadinglazyapp/src/protyle/render/av/row.ts封面选择器与 Emoji 面板则借助IntersectionObserver实现视口内懒加载app/src/protyle/header/Background.ts、app/src/emoji/index.ts。5.2 数据同步性能优化官方概述明确点出优化了数据同步性能issue #13216。同步模块位于 kernel/model/sync.go其中SyncDataDownload()与SyncDataUpload()分别承担拉取与推送数据仓库变更的任务二者均通过带 DNS 重试的通道执行syncRepoDownloadWithDNSRetry/syncRepoUploadWithDNSRetry并在操作前通过util.BroadcastByType(main, syncing, ...)向前端推送同步状态事件保证 UI 层的进度反馈。v3.1.14 在该链路上针对大量小文件/频繁变更场景做了性能调优。5.3 移除 Unicode PUA 字符移除 Unicode PUA 字符issue #13291PUAPrivate Use Area私有使用区字符在跨平台、跨设备显示时容易损坏或乱码v3.1.14 在相应输入/存储环节对这类字符进行清理提升文档在设备间流转的健壮性。六、缺陷修复本版本共修复 3 项明确缺陷缺陷说明反向链接关键词高亮不正确#13210反向链接面板中的关键词高亮位置/范围错误清理云端仓库失败#13243云端数据仓库清理操作偶发失败删除某些块后撤销异常#13254删除特定结构块后执行撤销内容恢复异常其中清理云端仓库失败涉及云端同步链路的异常处理与同步模块 kernel/model/sync.go 的仓库管理逻辑相关删除某些块后撤销异常则与文档树的撤销/重做UndoLog机制相关。七、依赖升级v3.1.14 完成了 4 项底层依赖升级均为图表渲染与文档处理关键组件依赖升级版本用途Mermaidv11.4.0#13209流程图、时序图等图表渲染flowchart.jsv1.18.0#13276经典流程图渲染pdfcpuv0.9.1#13305PDF 处理内核侧FSRSv3.3.0#13323闪卡Riff间隔重复排程算法其中FSRS是闪卡复习的排程核心其升级直接影响卡片到期时间与复习计划的计算精度Mermaid与flowchart.js则对应编辑器中的图表块渲染体验。八、开发者 API 与内核能力更新v3.1.14 面向插件开发者与高级用户提供了 4 项关键能力值得重点关注。8.1 内核 API/api/block/getBlockKramdown改进该 API 用于按块 ID 获取块的 KramdownSiYuan 内部标记格式内容本次改进issue #13183为请求参数引入了mode字段支持两种导出模式mdMarkdown 标记符模式使用标记符如**加粗**、链接导出textmark文本标记模式使用span标签导出保留更细粒度的行级样式信息。对应实现位于 kernel/api/block.go 的getBlockKramdown处理函数id : arg[id].(string) if util.InvalidIDPattern(id, ret) { return } // mdMarkdown 标记符模式使用标记符导出 // textmark文本标记模式使用 span 标签导出 // https://github.com/siyuan-note/siyuan/issues/13183 mode : md if modeArg : arg[mode]; nil ! modeArg { mode modeArg.(string) if md ! mode textmark ! mode { ret.Code -1 ret.Msg Invalid mode return } }注意两点使用前提mode仅接受md与textmark两个取值传入其他值将返回错误该接口在只读角色发布访问上下文下会校验发布访问权限无权限时返回空内容。路由注册位于 kernel/api/router.go同时提供批量版本/api/block/getBlockKramdownskernel/api/block.go 起支持一次传入多个ids批量获取二者均需通过认证与管理员角色校验model.CheckAuth、model.CheckAdminRole。8.2updateProtyleToolbar返回的工具栏配置支持热键插件可以通过覆写updateProtyleToolbar(toolbar)方法自定义编辑器Protyle工具栏项v3.1.14 起该方法返回的工具栏配置可以直接声明热键issue #13277。插件基类中的默认实现位于 app/src/plugin/index.ts原样返回传入的工具栏数组public updateProtyleToolbar(toolbar: Arraystring | IMenuItem) { return toolbar; }在工具栏装配处app/src/protyle/toolbar/index.ts渲染引擎会读取插件配置的hotkey字段并与全局快捷键配置中的插件项进行匹配window.siyuan.config.keymap.plugin[item.name][toolbarItem.name].custom从而让插件工具栏按钮响应快捷键触发。8.3 兼容设置代码块最大高度后的换行行为针对代码块最大高度这一用户设置v3.1.14 兼容了其与换行行为的组合表现issue #12726确保设置了最大高度后代码块内的滚动与换行符合预期。8.4 内核在/caldav/路径提供 CalDAV 服务本版本最重磅的内核级能力内核新增 CalDAV 服务PR #13321在路径/caldav/提供日历同步能力。这意味着第三方日历客户端如支持 CalDAV 的手机日历、桌面日历应用可以直接与 SiYuan 数据同步日历事件。完整实现位于 kernel/model/caldav.go可以梳理出其路径规划与存储模型路径规划kernel/model/caldav.go/caldav # 根 /caldav/principals # 用户主体集合 /caldav/principals/main # 当前用户主体 /caldav/principals/main/calendars # 日历 HomeSet /caldav/principals/main/calendars/default # 默认日历 /caldav/principals/main/calendars/default/{id}.ics # 日历事件对象存储模型每个日历是一个目录每个事件是一个标准iCalendar.ics文件日历元数据保存在calendars.json中CalDavCalendarsMetaDataFilePath。首次启动时若元数据文件不存在会自动创建名为default的默认日历defaultCalendar见 kernel/model/caldav.go支持的事件组件为VEVENT与VTODOdefaultCalendar caldav.Calendar{ Path: CalDavDefaultCalendarPath, Name: CalDavDefaultCalendarName, Description: Default calendar, MaxResourceSize: calendarMaxResourceSize, SupportedComponentSet: calendarSupportedComponentSet, }后端接口CalDavBackend实现了go-webdav/caldav库所需的全部接口CurrentUserPrincipal、CalendarHomeSetPath、CreateCalendar、ListCalendars、GetCalendar、DeleteCalendar、PutCalendarObject、ListCalendarObjects、GetCalendarObject、QueryCalendarObjects、DeleteCalendarObject因此天然兼容各类标准 CalDAV 客户端。内核还提供了配套的 DAV 基础能力实现kernel/model/dav.go用于路径与目录的映射。九、升级与下载v3.1.14 属于 v3.1.x 系列的一个常规发布升级路径平滑。内核与桌面端Electron同步更新用户可覆盖安装对应平台安装包在应用内也可通过设置 → 关于检查更新。若想深入了解本版本涉及的代码可在仓库中重点查看以下位置数据库计算算子kernel/av/calc.go、kernel/av/value.go同步链路kernel/model/sync.go文件名过滤kernel/util/file.go块 Kramdown APIkernel/api/block.go、kernel/api/router.goCalDAV 服务kernel/model/caldav.go、kernel/model/dav.go插件工具栏app/src/plugin/index.ts、app/src/protyle/toolbar/index.ts属性视图渲染app/src/protyle/render/av/cell.ts、app/src/protyle/render/av/row.ts结语v3.1.14 虽然没有引入颠覆性的新模块除了内置 CalDAV 这一亮点但它用 30 项细节改进把数据库计算、编辑器拖拽、导入导出、搜索高亮和同步性能的整体体验推高了一个台阶。其中唯一值百分比补齐了属性视图的统计能力矩阵/api/block/getBlockKramdown的mode参数为外部工具与插件接入提供了更灵活的标记导出选择而/caldav/服务的落地则预示着 SiYuan 向个人数据中枢方向迈出的重要一步。对于深度用户而言v3.1.14 值得立即升级对于插件开发者而言本节梳理的 API 变化则值得逐一验证利用。【免费下载链接】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），仅供参考