思源笔记 v3.3.1 版本更新详解ISO 周模板函数、数据库细节修复与开发者 API 增强【免费下载链接】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.1 繁体中文更新日志 为核心脉络逐条拆解 v3.3.1 的改进功能、缺陷修复、开发重构与面向开发者的新增能力并结合本仓库内核kernel与前端app源码给出实现级佐证。读完本文你将掌握 ISO 8601 周历模板函数的用法与实现原理、v3.3.1 中数据库/搜索/发布等模块的细节行为变化以及新增的事件总线和内核 API 的调用方式。版本概述v3.3.1 是一个以「改进细节」为主的维护版本共包含14 项功能改进、7 项缺陷修复、1 项开发重构以及 3 项面向开发者的变更覆盖编辑器、数据库属性视图、模板、搜索、发布、移动端Android / HarmonyOS NEXT与桌面端 Electron 等多个模块。官方概述仅一句「該版本改進了一些細節」但实际改动横跨前后端且新增了多个可被插件直接使用的事件与内核接口值得逐条深读。说明本文涉及的功能与代码均以当前仓库为事实依据涉及版本能力如 Electron 升级以发布记录表述为准当前仓库依赖版本可能已进一步升级。改进功能详解1. 支援從剪貼簿讀取檔案路徑v3.3.1 起在编辑器内可以通过粘贴操作直接识别剪贴板中的本地文件路径并读取对应文件免去了手动通过「资源文件」面板引入的步骤。这提升了从文件管理器复制路径后直接插入资源的效率适用于图片、附件等资源类型。2. 新增模板函數 ISOYear、ISOMonth 和 ISOWeekDate这是 v3.3.1 面向模板系统最重要的新增能力。此前模板函数已有ISOWeek可以获取 ISO 8601 周数但周数跨年时如 1 月 1 日属于上一年第 52/53 周年份归属并不直观因此本次补齐了三个配套函数。函数注册位置位于内核模板函数注册表 kernel/filesys/template.go它们与Weekday、WeekdayCN、ISOWeek等一起被注入模板函数映射ret[Weekday] util.Weekday ret[WeekdayCN] util.WeekdayCN ret[WeekdayCN2] util.WeekdayCN2 ret[ISOWeek] util.ISOWeek ret[ISOYear] util.ISOYear ret[ISOMonth] util.ISOMonth ret[ISOWeekDate] util.ISOWeekDate底层实现位于 kernel/util/time.go函数签名返回值语义ISOYearISOYear(date time.Time) int返回 date 所在的 ISO 8601 年份周数归属年份ISOMonthISOMonth(date time.Time) int返回 date 所在 ISO 周的周四所在自然月份ISOWeekDateISOWeekDate(day int, date time.Time) time.Time返回 date 所在 ISO 周内指定星期几的具体日期day周一1 … 周日7其中ISOYear直接复用 Go 标准库time.Time.ISOWeek()返回的年份分量ISOMonth通过「找到该 ISO 年份的 1 月 4 日必然属于第 1 周→ 反推第 1 周周四 → 按(isoWeek-1)*7天偏移得到目标周周四」的算法计算月份规避了跨年周数归属歧义ISOWeekDate则以周一为周起点向前回溯到本周一后再偏移day-1天得到目标日期。模板中的用法示例模板字段或动态日期场景{{ now | date 2006-01-02 }} 的 ISO 周{{ now | ISOWeek }} {{ now | date 2006-01-02 }} 的 ISO 年份{{ now | ISOYear }} {{ now | date 2006-01-02 }} 所在周的周四{{ now | ISOMonth }} {{ now | date 2006-01-02 }} 所在周周一{{ now | ISOWeekDate 1 | date 2006-01-02 }}注意模板管道中函数以函数名直接调用即可内核通过template.FuncMap完成注册开发者无需额外引入。3. 動態圖示顯示週數時年份改為 ISOYear配合第 2 项动态图标动态日期图标在展示周数时年份不再使用自然年而是改用 ISO 8601 周历年份ISOYear。修复了跨年场景下「周数显示为 2026 年第 1 周但年份仍显示 2025」这类不一致问题。从源码结构看动态图标渲染的年份取数逻辑已切换到ISOYear与模板函数共用同一实现。4. 改進資料庫範本欄位分組数据库属性视图中的模板类型字段在分组视图下的渲染得到改进。结合内核 kernel/av/group.go 的分组逻辑模板字段的计算值此前在分组时可能出现分组键不稳定或与筛选条件不一致的情况v3.3.1 对分组键的取用时机与模板渲染顺序做了调整使模板字段的分组结果与表格视图保持一致。5. 支援在 HarmonyOS NEXT 上透過其他應用程式開啟資源檔案移动端适配改进。HarmonyOS NEXT 版本现在支持通过系统「打开方式」调用其他应用打开思源笔记中的资源文件图片、PDF、文档等。HarmonyOS 入口位于 kernel/harmony/kernel.go通过文件路径授权与系统FileProvider/Ability 调用链完成具体打开动作由端侧实现。6. 發布代理中增加基於 Cookie 的認證面向发布Publish场景的安全增强发布代理现在支持基于 Cookie 的认证用于受密码保护的发布页面。内核实现位于 kernel/model/publish_access.gofunc SetPublishAuthCookie(c *gin.Context, ID string, password string) { authCookie : util.SHA256Hash([]byte(ID password)) http.SetCookie(c.Writer, http.Cookie{ Name: publish-auth- ID, Value: authCookie, MaxAge: 24 * 60 * 60, Path: /, Secure: util.SSL, HttpOnly: true, }) } func CheckPublishAuthCookie(c *gin.Context, ID string, password string) bool { authCookie, err : c.Request.Cookie(publish-auth- ID) return err nil authCookie.Value util.SHA256Hash([]byte(IDpassword)) }机制要点登录成功后服务端下发名为publish-auth-{ID}的 Cookie值为SHA256(ID password)有效期24 小时并带有HttpOnly标记Secure视当前是否启用 SSL 而定后续对受保护路径的访问内核通过 kernel/api/block.go 等处的CheckPublishAuthCookie校验 Cookie无需每次重复输入密码该 Cookie 覆盖块接口、大纲接口、文件树接口等多个发布相关访问路径统一由 kernel/model/publish_access.go 中的发布访问控制逻辑裁决。对于需要长时间免密访问发布站点的场景这显著改善了代理缓存与浏览器会话的可用性。7. 動態圖示預設使用目前日期动态图标在新建/初始化时默认日期取当前日期而非固定占位日期或上次使用的日期。此项配合第 2、3 项的 ISO 周历函数使动态日期图标从创建起即处于正确的周/年上下文。8. 改進模板語法高亮模板输入场景模板字段、模板片段的语法高亮增强。前端模板渲染涉及 kernel/filesys/template.go 提供的BuiltInTemplateFuncs基于 Gotext/template与 Masterminds/sprig语法高亮的改进让{{ ... }}管道表达式、函数名与参数在编辑时更易区分降低手写模板出错的概率。9. 改進清單塊變更時資料庫綁定塊的同步当列表块list item内容变更时数据库属性视图中与该列表块绑定的行数据能够更及时、更完整地同步。从源码结构看该同步链路涉及 kernel/model/attribute_view.go 中绑定块解析ParseAttributeView/GetBlockKeyValues以及块变更事务的联动刷新v3.3.1 修复了部分场景下列表块改动后数据库行未刷新的滞后问题。10. 改進 Android 鍵盤工具列的顯示高度Android 端软键盘弹出时编辑器顶部工具条的显示高度计算得到修正避免键盘工具条被系统导航栏遮挡或高度跳动。此为移动端键盘显示逻辑的细节适配。11. 分割線高度隨字體大小調整水平分割线---的渲染高度现在会随编辑器字体大小的缩放而自适应调整避免字体放大后分割线过细或位置错位属于排版细节改进。12. 改進新筆記本或文件時文件樹自訂排序的穩定性在创建新的笔记本或文档时文件树的自定义排序按自定义顺序拖拽排序不再因新建条目而被打乱或回退到默认排序。此项改进了文件树排序状态的持久化与新建操作的交互顺序。13. 塊引用搜尋和全域搜尋結果顯示引用計數搜索体验增强块引用搜索与全局搜索的结果条目现在会显示引用计数让用户直观了解每个结果被引用/被反链的次数。该计数信息由内核搜索链路提供参见 kernel/model/search.go 与 kernel/search/find.go前端结果面板将其渲染为徽标展示。14. 改進資料庫彙總範本渲染数据库汇总Rollup字段的模板渲染得到改进。汇总字段支持通过模板对关联字段进行计算展示参见 kernel/model/attribute_view.go 中汇总相关实现与 kernel/av/calc_template.gov3.3.1 修正了部分模板表达式在汇总场景下计算时机与结果格式的异常。修復缺陷詳解1. 某些情況下引用塊自訂屬性遺失修复了特定操作序列如复制粘贴、文档移动后引用块块引用block ref上自定义属性丢失的问题。涉及 kernel/model/virutalref.go 与块属性持久化链路确保引用块的自定义属性与源块保持同步。2. 資料庫日期欄位「預設填滿建立時間」自動填入時間值不正確数据库日期字段开启「默认填满创建时间」选项后自动填入的时间值在部分时区/场景下出现偏移。修复后该选项按块实际创建时间精确填充对应前端设置项setAttrViewColDateFillCreated参见 app/src/types/index.d.ts。3. 搜尋文件標籤時關鍵字高亮多出井號搜索文档标签时关键字高亮会额外多渲染一个#号。修复后高亮边界与标签本体对齐不再包含井号前缀。4. 資料庫總表範本計算不正確数据库总表汇总/Total视图下模板列的计算结果修正涉及 kernel/av/calc.go 与 kernel/av/calc_template.go 的模板求值路径修复了特定表达式组合下总表值错误的问题。5. 資料庫複選框欄位更新時間不斷變化数据库复选框中勾选状态未实际改变时「更新时间」字段仍会不断变化。修复后仅当复选值真正变更时才触发更新时间更新避免无谓的索引与历史记录膨胀。6. 資料庫相對日期篩選不正確数据库日期字段使用「相对日期」如「Is relative to today」等筛选算子参见 app/src/types/index.d.ts 中的筛选算子定义进行筛选时结果不正确的问题。修复了相对日期计算基准与当日零点对齐的偏差。7. 摺疊標題下塊的摺疊狀態在某些情況下不正確修复了折叠标题heading下子块的折叠状态在文档切换、内容更新后偶发错乱的问题涉及 kernel/treenode/heading.go 与前端折叠状态管理确保标题折叠状态随文档数据正确重建。開發重構升級至 Electron v37.4.0桌面端将 Electron 运行时升级至v37.4.0同步获得上游 Chromium 与 Node.js 的安全修复与性能改进。桌面端入口与打包配置位于 app/electron/main.js 及 app/electron-builder.yml 等文件升级后桌面端渲染进程与主进程的兼容性已按 v37 API 验证。说明当前仓库package.json中 electron 依赖版本为42.6.1app/package.json说明后续版本已进一步升级v3.3.1 发布时的升级目标为 Electron v37.4.0以发布记录为准。開發者相關變更1. 新增插件事件匯流排 code-language-update 與 code-language-change面向插件开发者的新事件前端事件总线新增code-language-update与code-language-change两个事件类型定义位于 app/src/types/index.d.tstype TEventBus ... | code-language-update | code-language-change | ...事件发射点位于代码块语言切换与代码块工具栏操作处 app/src/protyle/toolbar/index.tscode-language-update代码块语言被更新如通过工具栏修改语言时触发code-language-change代码块语言发生变更时触发。插件可通过事件总线订阅这两个事件在代码块语言变化时执行自定义逻辑如重新触发高亮、统计语言分布等this.eventBus.on(code-language-update, (eventDetail) { // eventDetail 中携带代码块相关信息 });2. 新增核心介面 getAttributeViewBoundBlockIDs 與 getAttributeViewItemIDs内核新增两个属性视图数据库查询接口路由注册于 kernel/api/router.go接口请求方法功能/api/av/getAttributeViewBoundBlockIDsByItemIDsPOST根据数据库行itemID 列表返回其绑定的块 ID 列表/api/av/getAttributeViewItemIDsByBoundIDsPOST根据绑定块 ID 列表返回其所属数据库行itemID 列表请求参数与实现位于 kernel/api/av.go二者均接收avID属性视图 ID加一个 ID 数组返回map[string]string映射// POST /api/av/getAttributeViewItemIDsByBoundIDs { avID: 20240101000000-abc123, blockIDs: [20240102000000-def456, 20240103000000-ghi789] }底层实现位于 kernel/model/attribute_view.go通过av.ParseAttributeView(avID)解析属性视图再调用attrView.GetBlockKeyValues()建立块 ID 与行 ID 的双向映射未匹配到的 ID 返回空字符串。这两个接口解决了**「绑定块 ↔ 数据库行」双向反查**的需求对插件实现数据库联动、行级定位等功能非常实用。3. 提升開發環境前端編譯效能开发模式下前端构建性能优化。前端构建由 app/webpack.config.js 管理本次优化涉及开发服务器缓存与构建管线配置缩短了热更新与冷启动等待时间提升插件/主题开发者的迭代效率。下载与升级v3.3.1 的安装包与升级包通过官方发布渠道分发覆盖 Windows、macOSIntel/Apple Silicon、Linuxamd64/arm64、Android、iOS、HarmonyOS NEXT 等平台从 v3.3.0 及更早版本升级时建议先备份工作空间参见 docs/WORKSPACE.zh-CN.md再按各平台惯例进行覆盖安装或包管理器升级。小结v3.3.1 虽然在发布记录中被概括为「改進了一些細節」但实际改动密度相当高模板系统获得 ISO 周历三件套ISOYear/ISOMonth/ISOWeekDate配合动态图标周数年份修正周维度的时间计算彻底走向 ISO 8601 标准数据库模块修复了模板字段分组、汇总模板计算、相对日期筛选、复选框更新时间抖动等多个边界问题发布模块新增基于 Cookie 的认证受密码保护的发布页面可用性显著提升开发者侧新增两个代码块语言事件与两个属性视图双向反查内核接口进一步降低了插件与数据库/编辑器深度集成的门槛。对于正在使用或二次开发思源笔记的开发者建议优先关注模板 ISO 函数与getAttributeViewBoundBlockIDs/getAttributeViewItemIDs两个新接口它们分别是「模板计算能力」与「数据库联动能力」的增量入口。【免费下载链接】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），仅供参考