SiYuan v3.6.1 版本解析外观主题内核 API/api/setting/setTheme与/api/ui/reloadTheme落地详解【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuanSiYuan v3.6.1 是一次以细节打磨为主题的版本围绕快速制卡撤销、数据库视图、发布服务安全、桌面端加载与退出同步等 10 项体验改进展开同时为开发者新增了两个外观相关的内核 API/api/setting/setTheme与/api/ui/reloadTheme。读完本文你将完整掌握 v3.6.1 的全部变更点并理解两个新 API 的参数结构、鉴权要求与内核侧的完整调用链参数解析 → 配置落盘 → 广播刷新可直接用于插件开发、主题脚本编写或自建 Agent 的场景化主题切换。版本概述v3.6.1 官方概括为此版本改进了一些细节变更分为三类改进功能10 项、修复缺陷1 项、开发者3 项。该版本不引入新的大特性重点在于修复已知问题、加固安全边界并为内核 API 补齐了外观主题管理能力。变更清单见 v3.6.1 官方中文说明。改进功能逐项解读快速制卡的撤销逻辑改进在使用快速制卡闪卡功能后执行撤销Undo的行为。此前撤销可能把制卡操作连带的块结构一并回滚、或回滚位置不符合预期v3.6.1 修正了撤销操作与制卡产生块之间的关联处理使撤销后的文档状态更符合用户直觉。数据库属性视图相关改进两项与数据库Attribute View相关的改进关联字段的默认图标数据库中关联类型字段此前展示的默认图标不符合语义本版本更换为更贴切的图标预览图片加载改进了数据库中图片字段预览的加载逻辑减少图片不显示或加载异常的情况。其他体验改进关闭用户指南笔记本的体验用户指南是随工作区附带的示例笔记本优化了其关闭流程避免误操作导致的困惑块链接的导出改进 Markdown / PDF 等导出格式中块引用链接的生成使导出后的链接可正确指向被引用块停靠栏图标的持久性在启用或禁用插件时停靠栏Dock图标的状态不再被意外重置插件卸载/安装后原有停靠布局得以保留RTL 与行级公式从右到左RTL语言环境下的文本方向不再错误地应用到行内数学公式公式的渲染方向保持正常桌面端主窗口加载优化了桌面客户端主窗口的加载过程退出时的数据同步改进了应用退出瞬间的数据同步时机降低退出过程中本地数据未落盘/未同步的风险。安全修复v3.6.1 修复了若干安全漏洞并在改进项中专门改进了发布服务的安全性。发布Publish是 SiYuan 将工作区以只读站点形式对外发布的功能属于直接暴露到公网的服务面其安全加固对自托管用户尤为关键。结合仓库结构发布相关的访问控制与密钥处理涉及 发布访问控制模型 与 发布配置建议自托管并开启了发布服务的用户在升级到 v3.6.1 后核对发布配置如访问密码、访问路径。安全类修复的具体技术细节通常不做公开披露仓库中不附带该漏洞的说明文档升级即可。开发者新增内核 API/api/setting/setTheme这是 v3.6.1 对开发者最实质的贡献之一——此前内核缺少一个直接切换主题的 RPC 接口插件或外部脚本只能改文件后再整体刷新。现在可以通过一次 POST 请求完成选择主题 指定亮/暗模式 设置外观模式。路由与鉴权路由注册位于 router.goginServer.Handle(POST, /api/setting/setTheme, model.CheckAuth, model.CheckAdminRole, model.CheckReadonly, setTheme)从三个中间件可以看出调用前提中间件含义model.CheckAuth需要携带有效认证Authorization请求头或会话 Cookiemodel.CheckAdminRole仅管理员角色可调用普通只读访问不可model.CheckReadonly只读模式下拒绝写操作请求参数处理函数setTheme位于 setting.go接受 JSON 参数{ theme: daylight, modes: [0, 1], appearanceMode: system }参数规则以源码为准themestring可选主题名。为空时本次调用不切换主题modesint 数组当theme非空时必填0表示应用到浅色模式1表示应用到深色模式[0,1]表示两种模式都应用。取值只允许 0 或 1出现其他值解析直接中断若theme非空而modes为空返回错误信息[modes] is required ([0] for light, [1] for dark, [0,1] for both)当theme为空时modes被静默忽略appearanceModestring可选外观模式取值为light/dark/system三种之一非法值返回invalid appearance mode错误。示例调用本地内核默认监听127.0.0.1:6806Authorization替换为你的访问密码curl -X POST http://127.0.0.1:6806/api/setting/setTheme \ -H Authorization: 你的访问密码 \ -H Content-Type: application/json \ -d {theme: midnight, modes: [0, 1]}内核侧实现校验与落盘setTheme校验通过后调用model.SetTheme(theme, modes, appearanceMode)其实现位于 appearance.go核心逻辑if theme ! { for _, mode : range modes { switch mode { case 0: if !containTheme(theme, Conf.Appearance.LightThemes) { return fmt.Errorf(theme [%s] not exists or not available for light mode, theme) } Conf.Appearance.ThemeLight theme case 1: if !containTheme(theme, Conf.Appearance.DarkThemes) { return fmt.Errorf(theme [%s] not exists or not available for dark mode, theme) } Conf.Appearance.ThemeDark theme } } } if appearanceMode ! { switch appearanceMode { case light: Conf.Appearance.ModeOS false Conf.Appearance.Mode 0 case dark: Conf.Appearance.ModeOS false Conf.Appearance.Mode 1 case system: Conf.Appearance.ModeOS true default: return fmt.Errorf(invalid appearance mode: %s, appearanceMode) } }从实现可以看到两层设计主题存在性校验containTheme会检查目标主题是否真实存在于已加载的主题列表中且分别匹配LightThemes/DarkThemes——也就是说一个主题能否用于浅色或深色模式取决于该主题自身声明了哪种模式主题目录内theme.json声明而不是调用方随意指定模式与跟随系统互斥light/dark会把ModeOS置为false并固定Mode为 0 或 1system则把ModeOS置为true让外观跟随操作系统。主题列表的加载入口是LoadThemesappearance.go它读取主题目录对应工作区外的themes目录仓库内置主题为 daylight 与 midnight。因此通过该 API 能切换到的主题必须以主题目录的形式真实存在于当前 SiYuan 的主题路径下——这正是/api/ui/reloadTheme存在的意义见下文。调用后的前端刷新setTheme落盘完成后setTheme处理函数还会执行model.InitAppearance() util.BroadcastByType(main, setAppearance, 0, , model.Conf.Appearance)即重新构建外观状态并通过 WebSocket 广播setAppearance事件把完整的外观配置推给所有已连接的前端客户端收到后即时换肤无需刷新页面。这一写配置 → 初始化外观 → 广播的三段式与内核中同类外观接口如setIcon见 setting.go保持一致是 SiYuan 外观类 API 的统一范式。开发者新增内核 API/api/ui/reloadTheme第二个新 API 用于在不重启内核的前提下重新扫描主题目录路由注册见 router.goginServer.Handle(POST, /api/ui/reloadTheme, model.CheckAuth, model.CheckAdminRole, model.CheckReadonly, reloadTheme)处理函数位于 ui.gofunc reloadTheme(c *gin.Context) { ret : gulu.Ret.NewResult() defer c.JSON(http.StatusOK, ret) model.LoadThemes() util.BroadcastByType(main, setAppearance, 0, , model.Conf.Appearance) }逻辑很直接调用LoadThemes()重新读取主题目录并刷新内存中的LightThemes/DarkThemes列表随后广播setAppearance让前端同步。鉴权要求与setTheme相同。两个 API 组合起来就构成一条完整的动态主题链路拷贝/写入主题文件到 themes 目录 │ ▼ POST /api/ui/reloadTheme 重新扫描主题目录 │ ▼ POST /api/setting/setTheme 选择主题并指定亮/暗模式、外观模式 │ ▼ 前端收到 setAppearance 广播即时换肤典型场景插件安装主题包后不必提示用户重启 SiYuan或者定时脚本根据系统时段在浅色/深色主题间切换。注意该能力要求客户端以管理员角色访问且目标主题文件本身合法含theme.json声明、CSS 资源齐全否则LoadThemes不会将其纳入可用列表setTheme的containTheme校验会直接报错。开发者表情符号全量展示页v3.6.1 还新增了一个静态 HTML 页面 emojis/index.html用于可视化展示当前渲染内核支持的全部 emoji 短码。其实现引用了编辑器渲染库 Lute 的GetEmojis()接口script src../../stage/protyle/js/lute/lute.min.js/script ... const emoji Lute.New().GetEmojis() Object.keys(emoji).forEach((key) { const value emoji[key].indexOf(http) -1 ? img src${emoji[key]}/ : emoji[key] emojiHTML div classemoji__item${value}nbsp;:${key}:/div })页面以网格形式渲染emoji 图形 短码配对如:smile:短码值若是外链图片则渲染为img。该页面对排查某个 emoji 短码在当前版本是否可用、显示为何种图形非常有用也便于插件开发者确认:key:形式的 emoji 语法全集无需再通过笔记逐一试探。配套的表情配置见 conf.json。版本获取v3.6.1 的发行包通过 SiYuan 官网下载页与 GitHub Releases 渠道发布见原文档下载一节。对于正在使用的用户直接通过客户端内置更新或下载对应平台安装包覆盖升级即可内核 API 的调用方插件、脚本、Agent 工具可在升级后按前文的路径与参数约定接入setTheme/reloadTheme无需修改现有配置。小结v3.6.1 的变更虽以细节修复为主但开发者侧的两个新 API 填补了内核外观管理的空缺/api/setting/setTheme提供了带存在性校验、支持亮/暗模式分别指定、并联动系统跟随模式的完整主题切换能力/api/ui/reloadTheme则打通了主题目录的热加载。两者都遵循 SiYuan 内核 API 的标准鉴权链CheckAuth→CheckAdminRole→CheckReadonly与落盘 setAppearance广播的刷新范式是插件生态和自动化脚本做主题管理的可靠落点。【免费下载链接】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），仅供参考
SiYuan v3.6.1 版本解析外观主题内核 API/api/setting/setTheme与/api/ui/reloadTheme落地详解【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuanSiYuan v3.6.1 是一次以细节打磨为主题的版本围绕快速制卡撤销、数据库视图、发布服务安全、桌面端加载与退出同步等 10 项体验改进展开同时为开发者新增了两个外观相关的内核 API/api/setting/setTheme与/api/ui/reloadTheme。读完本文你将完整掌握 v3.6.1 的全部变更点并理解两个新 API 的参数结构、鉴权要求与内核侧的完整调用链参数解析 → 配置落盘 → 广播刷新可直接用于插件开发、主题脚本编写或自建 Agent 的场景化主题切换。版本概述v3.6.1 官方概括为此版本改进了一些细节变更分为三类改进功能10 项、修复缺陷1 项、开发者3 项。该版本不引入新的大特性重点在于修复已知问题、加固安全边界并为内核 API 补齐了外观主题管理能力。变更清单见 v3.6.1 官方中文说明。改进功能逐项解读快速制卡的撤销逻辑改进在使用快速制卡闪卡功能后执行撤销Undo的行为。此前撤销可能把制卡操作连带的块结构一并回滚、或回滚位置不符合预期v3.6.1 修正了撤销操作与制卡产生块之间的关联处理使撤销后的文档状态更符合用户直觉。数据库属性视图相关改进两项与数据库Attribute View相关的改进关联字段的默认图标数据库中关联类型字段此前展示的默认图标不符合语义本版本更换为更贴切的图标预览图片加载改进了数据库中图片字段预览的加载逻辑减少图片不显示或加载异常的情况。其他体验改进关闭用户指南笔记本的体验用户指南是随工作区附带的示例笔记本优化了其关闭流程避免误操作导致的困惑块链接的导出改进 Markdown / PDF 等导出格式中块引用链接的生成使导出后的链接可正确指向被引用块停靠栏图标的持久性在启用或禁用插件时停靠栏Dock图标的状态不再被意外重置插件卸载/安装后原有停靠布局得以保留RTL 与行级公式从右到左RTL语言环境下的文本方向不再错误地应用到行内数学公式公式的渲染方向保持正常桌面端主窗口加载优化了桌面客户端主窗口的加载过程退出时的数据同步改进了应用退出瞬间的数据同步时机降低退出过程中本地数据未落盘/未同步的风险。安全修复v3.6.1 修复了若干安全漏洞并在改进项中专门改进了发布服务的安全性。发布Publish是 SiYuan 将工作区以只读站点形式对外发布的功能属于直接暴露到公网的服务面其安全加固对自托管用户尤为关键。结合仓库结构发布相关的访问控制与密钥处理涉及 发布访问控制模型 与 发布配置建议自托管并开启了发布服务的用户在升级到 v3.6.1 后核对发布配置如访问密码、访问路径。安全类修复的具体技术细节通常不做公开披露仓库中不附带该漏洞的说明文档升级即可。开发者新增内核 API/api/setting/setTheme这是 v3.6.1 对开发者最实质的贡献之一——此前内核缺少一个直接切换主题的 RPC 接口插件或外部脚本只能改文件后再整体刷新。现在可以通过一次 POST 请求完成选择主题 指定亮/暗模式 设置外观模式。路由与鉴权路由注册位于 router.goginServer.Handle(POST, /api/setting/setTheme, model.CheckAuth, model.CheckAdminRole, model.CheckReadonly, setTheme)从三个中间件可以看出调用前提中间件含义model.CheckAuth需要携带有效认证Authorization请求头或会话 Cookiemodel.CheckAdminRole仅管理员角色可调用普通只读访问不可model.CheckReadonly只读模式下拒绝写操作请求参数处理函数setTheme位于 setting.go接受 JSON 参数{ theme: daylight, modes: [0, 1], appearanceMode: system }参数规则以源码为准themestring可选主题名。为空时本次调用不切换主题modesint 数组当theme非空时必填0表示应用到浅色模式1表示应用到深色模式[0,1]表示两种模式都应用。取值只允许 0 或 1出现其他值解析直接中断若theme非空而modes为空返回错误信息[modes] is required ([0] for light, [1] for dark, [0,1] for both)当theme为空时modes被静默忽略appearanceModestring可选外观模式取值为light/dark/system三种之一非法值返回invalid appearance mode错误。示例调用本地内核默认监听127.0.0.1:6806Authorization替换为你的访问密码curl -X POST http://127.0.0.1:6806/api/setting/setTheme \ -H Authorization: 你的访问密码 \ -H Content-Type: application/json \ -d {theme: midnight, modes: [0, 1]}内核侧实现校验与落盘setTheme校验通过后调用model.SetTheme(theme, modes, appearanceMode)其实现位于 appearance.go核心逻辑if theme ! { for _, mode : range modes { switch mode { case 0: if !containTheme(theme, Conf.Appearance.LightThemes) { return fmt.Errorf(theme [%s] not exists or not available for light mode, theme) } Conf.Appearance.ThemeLight theme case 1: if !containTheme(theme, Conf.Appearance.DarkThemes) { return fmt.Errorf(theme [%s] not exists or not available for dark mode, theme) } Conf.Appearance.ThemeDark theme } } } if appearanceMode ! { switch appearanceMode { case light: Conf.Appearance.ModeOS false Conf.Appearance.Mode 0 case dark: Conf.Appearance.ModeOS false Conf.Appearance.Mode 1 case system: Conf.Appearance.ModeOS true default: return fmt.Errorf(invalid appearance mode: %s, appearanceMode) } }从实现可以看到两层设计主题存在性校验containTheme会检查目标主题是否真实存在于已加载的主题列表中且分别匹配LightThemes/DarkThemes——也就是说一个主题能否用于浅色或深色模式取决于该主题自身声明了哪种模式主题目录内theme.json声明而不是调用方随意指定模式与跟随系统互斥light/dark会把ModeOS置为false并固定Mode为 0 或 1system则把ModeOS置为true让外观跟随操作系统。主题列表的加载入口是LoadThemesappearance.go它读取主题目录对应工作区外的themes目录仓库内置主题为 daylight 与 midnight。因此通过该 API 能切换到的主题必须以主题目录的形式真实存在于当前 SiYuan 的主题路径下——这正是/api/ui/reloadTheme存在的意义见下文。调用后的前端刷新setTheme落盘完成后setTheme处理函数还会执行model.InitAppearance() util.BroadcastByType(main, setAppearance, 0, , model.Conf.Appearance)即重新构建外观状态并通过 WebSocket 广播setAppearance事件把完整的外观配置推给所有已连接的前端客户端收到后即时换肤无需刷新页面。这一写配置 → 初始化外观 → 广播的三段式与内核中同类外观接口如setIcon见 setting.go保持一致是 SiYuan 外观类 API 的统一范式。开发者新增内核 API/api/ui/reloadTheme第二个新 API 用于在不重启内核的前提下重新扫描主题目录路由注册见 router.goginServer.Handle(POST, /api/ui/reloadTheme, model.CheckAuth, model.CheckAdminRole, model.CheckReadonly, reloadTheme)处理函数位于 ui.gofunc reloadTheme(c *gin.Context) { ret : gulu.Ret.NewResult() defer c.JSON(http.StatusOK, ret) model.LoadThemes() util.BroadcastByType(main, setAppearance, 0, , model.Conf.Appearance) }逻辑很直接调用LoadThemes()重新读取主题目录并刷新内存中的LightThemes/DarkThemes列表随后广播setAppearance让前端同步。鉴权要求与setTheme相同。两个 API 组合起来就构成一条完整的动态主题链路拷贝/写入主题文件到 themes 目录 │ ▼ POST /api/ui/reloadTheme 重新扫描主题目录 │ ▼ POST /api/setting/setTheme 选择主题并指定亮/暗模式、外观模式 │ ▼ 前端收到 setAppearance 广播即时换肤典型场景插件安装主题包后不必提示用户重启 SiYuan或者定时脚本根据系统时段在浅色/深色主题间切换。注意该能力要求客户端以管理员角色访问且目标主题文件本身合法含theme.json声明、CSS 资源齐全否则LoadThemes不会将其纳入可用列表setTheme的containTheme校验会直接报错。开发者表情符号全量展示页v3.6.1 还新增了一个静态 HTML 页面 emojis/index.html用于可视化展示当前渲染内核支持的全部 emoji 短码。其实现引用了编辑器渲染库 Lute 的GetEmojis()接口script src../../stage/protyle/js/lute/lute.min.js/script ... const emoji Lute.New().GetEmojis() Object.keys(emoji).forEach((key) { const value emoji[key].indexOf(http) -1 ? img src${emoji[key]}/ : emoji[key] emojiHTML div classemoji__item${value}nbsp;:${key}:/div })页面以网格形式渲染emoji 图形 短码配对如:smile:短码值若是外链图片则渲染为img。该页面对排查某个 emoji 短码在当前版本是否可用、显示为何种图形非常有用也便于插件开发者确认:key:形式的 emoji 语法全集无需再通过笔记逐一试探。配套的表情配置见 conf.json。版本获取v3.6.1 的发行包通过 SiYuan 官网下载页与 GitHub Releases 渠道发布见原文档下载一节。对于正在使用的用户直接通过客户端内置更新或下载对应平台安装包覆盖升级即可内核 API 的调用方插件、脚本、Agent 工具可在升级后按前文的路径与参数约定接入setTheme/reloadTheme无需修改现有配置。小结v3.6.1 的变更虽以细节修复为主但开发者侧的两个新 API 填补了内核外观管理的空缺/api/setting/setTheme提供了带存在性校验、支持亮/暗模式分别指定、并联动系统跟随模式的完整主题切换能力/api/ui/reloadTheme则打通了主题目录的热加载。两者都遵循 SiYuan 内核 API 的标准鉴权链CheckAuth→CheckAdminRole→CheckReadonly与落盘 setAppearance广播的刷新范式是插件生态和自动化脚本做主题管理的可靠落点。【免费下载链接】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），仅供参考
