尧图网页设计 
SiYuan v3.5.0 提示块Callout Block全面解析功能特性、使用指南与源码实现【免费下载链接】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.5.0 版本官方变更记录app/changelogs/v3.5.x/v3.5.0/v3.5.0.md系统梳理该版本的核心特性——提示块Callout Block涵盖其背景、使用方式、类型体系与前端/内核的源码实现同时完整收录该版本的全部增强、缺陷修复与开发者相关变更。读完本文你将掌握提示块的创建与定制方法、五种内置类型的视觉与语义体系并理解 SiYuan 如何在数据模型、编辑器与搜索系统中落地这一新块类型。版本背景与重要注意事项v3.5.0 是 SiYuan 引入提示块的版本官方变更记录在概述中特别强调了两个使用前提更新后不支持回退使用新版创建了包含提示块的文档后若用旧版打开会导致提示块丢失。因此升级前建议备份数据仓库升级后不要再退回旧版本编辑含提示块的文档。批量升级文档数据版本号该版本会批量更新所有文档数据的规格版本号spec version首次启动时数据同步与索引重建可能耗时较长请耐心等待完成期间不要强制中断进程。这两个注意事项对应了变更列表中的“旧版本应用不再支持打开新版本文档”一项新旧版本间的文档格式规格不一致是设计使然而非数据损坏。核心特性提示块Callout Block什么是提示块提示块是一种带类型标识、图标与强调色边框的块级容器用于在文档中突出呈现注意事项、提示、警告等语义化内容。它由三部分构成图标callout-icon显示在块内的语义图标如 ✏️ / / ⚠️也可替换为自定义 Emoji 或动态图标标题callout-title块的类型文字说明如 NOTE、TIP正文内容块内的普通内容支持段落、列表、引用等子块。五种内置类型与配色体系从前端源码 app/src/protyle/wysiwyg/callout.ts 与样式源码 app/src/assets/scss/component/_typography.scss 可以确认提示块内置五种类型每种类型对应一个 CSS 变量控制的强调色类型默认图标CSS 颜色变量语义NOTE✏️--b3-callout-note一般性备注TIP--b3-callout-tip技巧与建议IMPORTANT❗--b3-callout-important重要说明WARNING⚠️--b3-callout-warning警告CAUTION--b3-callout-caution谨慎/危险在 SCSS 中.callout通过::before伪元素绘制左侧圆角色条宽度0.25em、带--b3-border-radius圆角并利用属性选择器[data-subtypeWARNING]、[data-subtypeTIP]等按块类型切换色条与.callout-info文字颜色当.callout-icon:empty时图标区域自动隐藏保持布局整洁。这意味着主题开发者可通过覆盖上述 CSS 变量定制各类型的强调色。如何创建与编辑提示块在桌面端编辑器中可通过以下方式使用提示块插入在块菜单Block Menu中选择插入提示块或输入触发引用块菜单后选择提示块类型编辑属性鼠标悬停提示块点击块图标或使用对应菜单项打开“提示类型设置”对话框源码中由updateCalloutType实现对话框标题为window.siyuan.languages.callout宽度桌面端520px、移动端92vw在该对话框中可以点击图标区域打开 Emoji 面板更换图标支持选择自定义 Emoji生成img classcallout-img与动态图标api/icon/getDynamicIcon修改**类型Type**输入框块类型值会写入块的data-subtype属性输入任意自定义类型同样有效修改**标题Title**输入框标题内容经protyle.lute.Md2BlockDOM解析为块 DOM 后写入.callout-title若标题留空则自动取类型首字母大写、其余小写的字符串如NOTE作为默认标题快速选择内置类型点击类型输入框右侧的下拉图标弹出提示选择菜单Constants.MENU_CALLOUT_SELECT callout-select见 app/src/constants.ts列出上述五种内置类型选择后同步更新类型值、图标与标题。所有修改通过transaction(protyle, doOperations, undoOperations)提交为可撤销/重做的操作记录action: update与普通块编辑保持一致的历史行为。提示块的底层数据与块类型体系从内核源码可以确认提示块已成为一等公民的块类型块类型映射在 kernel/treenode/node.go 中NodeCallout: callout将 DOM 节点类型映射为块类型callout使其进入统一的块类型体系块树支持在 kernel/treenode/blocktree.go 中callout与文档d、块引用b、列表l、列表项i、超级块s等并列参与块树遍历逻辑搜索过滤在 kernel/model/storage.go 中搜索准则Criterion的块类型过滤结构CriterionTypes新增了Callout bool字段即搜索时可以单独勾选/排除提示块类型。由此可以推断提示块在存储层面与引用块b存在亲缘关系——它本质上是一种带语义子类型的容器块data-subtype属性承担了类型区分职责与引用块的实现思路一致。查询嵌入块支持 UNION 查询v3.5.0 增强了查询嵌入块的能力查询嵌入块支持 UNION 查询。其实现位于 kernel/sql/block_query.go内核 SQL 查询接口/api/query/sql在解析阶段同时兼容两种语法——既支持使用自定义解析器处理||连接符以支持文本拼接运算也支持通过 vitess 的sqlparser识别UNION语句结构。源码注释明确指出由于支持||操作符的自定义解析器无法处理UNION实现上以||操作符为主、通过另一解析器补充 UNION 支持并在UNION解析分支中对union.Limit做统一的分页限制处理设置/补齐Limit与Offset。实际使用中在查询嵌入块或/api/query/sql中编写含UNION/UNION ALL的 SQL 即可合并多个结果集例如合并不同文档或不同类型块的查询结果。其他增强与改进v3.5.0 还包含以下值得关注的增强编辑与交互改进备注提示与 AI 工具提示备注Memo与 AI 助手的悬浮提示样式与触发行为得到优化改进打开块的位置定位从反链、搜索结果等入口打开块时定位更准确改进通过快捷键打开日记时的光标定位使用快捷键打开日记后光标直接落到编辑位置改进块拖拽块拖拽过程中的交互细节优化改进移动端大纲定位移动端大纲面板跳转定位更精准改进列表中“跳转到父块”的行为在列表项中使用该操作时行为更符合预期改进上下移动排序列表后的排序规则对有序列表上移/下移条目后的编号规则做了修正改进行级代码编辑行内代码的编辑体验优化改进插入资源文件去重插入同一资源时自动去重避免重复文件堆积。语言与平台支持在桌面端设置拼写检查语言可在桌面端设置中选择拼写检查语言添加韩语支持、添加土耳其语支持界面语言新增韩语与土耳其语对应 PR 分别见 v3.5.0 变更记录支持 MoonBit 编程语言的语法高亮代码块高亮新增 MoonBit 语言改进 macOS 上输入法兼容性修复 macOS 输入法组合输入场景下的兼容问题。性能改进数据索引性能索引构建与查询路径优化配合版本升级时的批量重建可缩短首次启动等待时间。缺陷修复本版本修复的缺陷包括数据库看板视图分组修改问题看板视图Kanban中分组字段修改异常在软换行后输入反引号导致的错误软换行后直接输入触发解析错误的场景关闭插件时执行卸载方法的问题插件关闭时错误执行uninstall方法的修复对应 PRZip 解压的安全漏洞修复压缩包解压过程中的安全风险涉及路径穿越类防护移动端无法切换工作空间移动端工作空间切换失效嵌入块导出错误包含嵌入块Embed Block的文档导出结果不正确数据仓库索引丢失导致内核退出数据仓库索引丢失时内核异常退出的问题。开发者相关变更面向插件与集市生态的变更插件更新导致停靠栏、工具栏和选项卡加载失败修复插件更新后 Dock、工具栏、Tab 组件加载失败的问题改进集市包索引集市Marketplace包索引的构建与刷新逻辑优化提升插件/主题市场可用性。升级建议与总结升级到 v3.5.0 前请确认以下事项做好数据仓库备份因为升级后无法回退旧版本无法打开含提示块的新版本文档预留足够时间等待批量版本号升级与索引重建完成升级过程中保持进程稳定升级后即可体验提示块这一核心新特性并结合搜索过滤Callout类型过滤与查询嵌入块的UNION能力构建更丰富的知识表达。提示块的引入标志着 SiYuan 在块语义体系上的进一步成熟它复用了既有的块树、事务与搜索框架仅需在节点类型映射、块树遍历与搜索过滤三处内核点位上登记新类型即可全面生效前端则通过data-subtype与 CSS 变量实现了高可定制的视觉体系。开发者若想深入研读可重点关注 app/src/protyle/wysiwyg/callout.ts、app/src/assets/scss/component/_typography.scss、kernel/treenode/node.go 与 kernel/sql/block_query.go 四处核心代码。【免费下载链接】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.5.0 提示块（Callout Block）全面解析：功能特性、使用指南与源码实现
SiYuan v3.5.0 提示块Callout Block全面解析功能特性、使用指南与源码实现【免费下载链接】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.5.0 版本官方变更记录app/changelogs/v3.5.x/v3.5.0/v3.5.0.md系统梳理该版本的核心特性——提示块Callout Block涵盖其背景、使用方式、类型体系与前端/内核的源码实现同时完整收录该版本的全部增强、缺陷修复与开发者相关变更。读完本文你将掌握提示块的创建与定制方法、五种内置类型的视觉与语义体系并理解 SiYuan 如何在数据模型、编辑器与搜索系统中落地这一新块类型。版本背景与重要注意事项v3.5.0 是 SiYuan 引入提示块的版本官方变更记录在概述中特别强调了两个使用前提更新后不支持回退使用新版创建了包含提示块的文档后若用旧版打开会导致提示块丢失。因此升级前建议备份数据仓库升级后不要再退回旧版本编辑含提示块的文档。批量升级文档数据版本号该版本会批量更新所有文档数据的规格版本号spec version首次启动时数据同步与索引重建可能耗时较长请耐心等待完成期间不要强制中断进程。这两个注意事项对应了变更列表中的“旧版本应用不再支持打开新版本文档”一项新旧版本间的文档格式规格不一致是设计使然而非数据损坏。核心特性提示块Callout Block什么是提示块提示块是一种带类型标识、图标与强调色边框的块级容器用于在文档中突出呈现注意事项、提示、警告等语义化内容。它由三部分构成图标callout-icon显示在块内的语义图标如 ✏️ / / ⚠️也可替换为自定义 Emoji 或动态图标标题callout-title块的类型文字说明如 NOTE、TIP正文内容块内的普通内容支持段落、列表、引用等子块。五种内置类型与配色体系从前端源码 app/src/protyle/wysiwyg/callout.ts 与样式源码 app/src/assets/scss/component/_typography.scss 可以确认提示块内置五种类型每种类型对应一个 CSS 变量控制的强调色类型默认图标CSS 颜色变量语义NOTE✏️--b3-callout-note一般性备注TIP--b3-callout-tip技巧与建议IMPORTANT❗--b3-callout-important重要说明WARNING⚠️--b3-callout-warning警告CAUTION--b3-callout-caution谨慎/危险在 SCSS 中.callout通过::before伪元素绘制左侧圆角色条宽度0.25em、带--b3-border-radius圆角并利用属性选择器[data-subtypeWARNING]、[data-subtypeTIP]等按块类型切换色条与.callout-info文字颜色当.callout-icon:empty时图标区域自动隐藏保持布局整洁。这意味着主题开发者可通过覆盖上述 CSS 变量定制各类型的强调色。如何创建与编辑提示块在桌面端编辑器中可通过以下方式使用提示块插入在块菜单Block Menu中选择插入提示块或输入触发引用块菜单后选择提示块类型编辑属性鼠标悬停提示块点击块图标或使用对应菜单项打开“提示类型设置”对话框源码中由updateCalloutType实现对话框标题为window.siyuan.languages.callout宽度桌面端520px、移动端92vw在该对话框中可以点击图标区域打开 Emoji 面板更换图标支持选择自定义 Emoji生成img classcallout-img与动态图标api/icon/getDynamicIcon修改**类型Type**输入框块类型值会写入块的data-subtype属性输入任意自定义类型同样有效修改**标题Title**输入框标题内容经protyle.lute.Md2BlockDOM解析为块 DOM 后写入.callout-title若标题留空则自动取类型首字母大写、其余小写的字符串如NOTE作为默认标题快速选择内置类型点击类型输入框右侧的下拉图标弹出提示选择菜单Constants.MENU_CALLOUT_SELECT callout-select见 app/src/constants.ts列出上述五种内置类型选择后同步更新类型值、图标与标题。所有修改通过transaction(protyle, doOperations, undoOperations)提交为可撤销/重做的操作记录action: update与普通块编辑保持一致的历史行为。提示块的底层数据与块类型体系从内核源码可以确认提示块已成为一等公民的块类型块类型映射在 kernel/treenode/node.go 中NodeCallout: callout将 DOM 节点类型映射为块类型callout使其进入统一的块类型体系块树支持在 kernel/treenode/blocktree.go 中callout与文档d、块引用b、列表l、列表项i、超级块s等并列参与块树遍历逻辑搜索过滤在 kernel/model/storage.go 中搜索准则Criterion的块类型过滤结构CriterionTypes新增了Callout bool字段即搜索时可以单独勾选/排除提示块类型。由此可以推断提示块在存储层面与引用块b存在亲缘关系——它本质上是一种带语义子类型的容器块data-subtype属性承担了类型区分职责与引用块的实现思路一致。查询嵌入块支持 UNION 查询v3.5.0 增强了查询嵌入块的能力查询嵌入块支持 UNION 查询。其实现位于 kernel/sql/block_query.go内核 SQL 查询接口/api/query/sql在解析阶段同时兼容两种语法——既支持使用自定义解析器处理||连接符以支持文本拼接运算也支持通过 vitess 的sqlparser识别UNION语句结构。源码注释明确指出由于支持||操作符的自定义解析器无法处理UNION实现上以||操作符为主、通过另一解析器补充 UNION 支持并在UNION解析分支中对union.Limit做统一的分页限制处理设置/补齐Limit与Offset。实际使用中在查询嵌入块或/api/query/sql中编写含UNION/UNION ALL的 SQL 即可合并多个结果集例如合并不同文档或不同类型块的查询结果。其他增强与改进v3.5.0 还包含以下值得关注的增强编辑与交互改进备注提示与 AI 工具提示备注Memo与 AI 助手的悬浮提示样式与触发行为得到优化改进打开块的位置定位从反链、搜索结果等入口打开块时定位更准确改进通过快捷键打开日记时的光标定位使用快捷键打开日记后光标直接落到编辑位置改进块拖拽块拖拽过程中的交互细节优化改进移动端大纲定位移动端大纲面板跳转定位更精准改进列表中“跳转到父块”的行为在列表项中使用该操作时行为更符合预期改进上下移动排序列表后的排序规则对有序列表上移/下移条目后的编号规则做了修正改进行级代码编辑行内代码的编辑体验优化改进插入资源文件去重插入同一资源时自动去重避免重复文件堆积。语言与平台支持在桌面端设置拼写检查语言可在桌面端设置中选择拼写检查语言添加韩语支持、添加土耳其语支持界面语言新增韩语与土耳其语对应 PR 分别见 v3.5.0 变更记录支持 MoonBit 编程语言的语法高亮代码块高亮新增 MoonBit 语言改进 macOS 上输入法兼容性修复 macOS 输入法组合输入场景下的兼容问题。性能改进数据索引性能索引构建与查询路径优化配合版本升级时的批量重建可缩短首次启动等待时间。缺陷修复本版本修复的缺陷包括数据库看板视图分组修改问题看板视图Kanban中分组字段修改异常在软换行后输入反引号导致的错误软换行后直接输入触发解析错误的场景关闭插件时执行卸载方法的问题插件关闭时错误执行uninstall方法的修复对应 PRZip 解压的安全漏洞修复压缩包解压过程中的安全风险涉及路径穿越类防护移动端无法切换工作空间移动端工作空间切换失效嵌入块导出错误包含嵌入块Embed Block的文档导出结果不正确数据仓库索引丢失导致内核退出数据仓库索引丢失时内核异常退出的问题。开发者相关变更面向插件与集市生态的变更插件更新导致停靠栏、工具栏和选项卡加载失败修复插件更新后 Dock、工具栏、Tab 组件加载失败的问题改进集市包索引集市Marketplace包索引的构建与刷新逻辑优化提升插件/主题市场可用性。升级建议与总结升级到 v3.5.0 前请确认以下事项做好数据仓库备份因为升级后无法回退旧版本无法打开含提示块的新版本文档预留足够时间等待批量版本号升级与索引重建完成升级过程中保持进程稳定升级后即可体验提示块这一核心新特性并结合搜索过滤Callout类型过滤与查询嵌入块的UNION能力构建更丰富的知识表达。提示块的引入标志着 SiYuan 在块语义体系上的进一步成熟它复用了既有的块树、事务与搜索框架仅需在节点类型映射、块树遍历与搜索过滤三处内核点位上登记新类型即可全面生效前端则通过data-subtype与 CSS 变量实现了高可定制的视觉体系。开发者若想深入研读可重点关注 app/src/protyle/wysiwyg/callout.ts、app/src/assets/scss/component/_typography.scss、kernel/treenode/node.go 与 kernel/sql/block_query.go 四处核心代码。【免费下载链接】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），仅供参考