思源笔记 v2.12.7 版本发布详解编辑器交互优化、关键缺陷修复与 API 演进【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan本文依据仓库内发布说明 app/changelogs/v2.8.4-v2.12.8/v2.12.7/v2.12.7_zh_CHT.md 撰写。该版本是一次以修复缺陷、改进细节为主的稳定迭代聚焦 Pad 端编辑器操作、表情面板交互、复制粘贴行为、数据库表格视图、移动端滚动与闪卡复习等日常高频使用场景同时面向开发者开放了文件树接口的新参数。文中除忠实梳理每条变更外还结合当前仓库源码对若干关键机制进行了印证与展开便于理解这些改动背后的实现原理。版本定位与变更总览思源笔记 v2.12.7 是一个典型的次版本迭代。发布说明开篇即明确其定位该版本主要是修复缺陷和改进细节没有引入颠覆性的新特性而是围绕编辑器、移动端、插件市场、闪卡等模块做细粒度打磨。这一策略保证了主版本如随后的 v3.x 系列上线前日常使用体验的稳定性。整个变更记录分为四大类具体数量与主题如下表所示类别数量主要涉及模块改进功能14 项Pad 端编辑器、表情面板、复制粘贴、插件市场、停靠栏、闪卡、移动端、文件树修复缺陷5 项Android 端、表情对话框、数据库表格视图、闪卡复习、卡片复习状态机开发重构2 项Electron 升级至 v28.2.1、KaTeX 升级至 v0.16.9开发者API/细节2 项listDocsByPath新参数、数据库表格视图文本列换行滚动Pad 端与编辑器交互改进撤销、重做与 Tab 按钮补齐#6804v2.12.7 在Pad 端平板新增了撤销、重做和 Tab 按钮对应 GitHub issue #6804。此前 Pad 用户需要依赖系统键盘或手势完成撤销、重做与缩进操作触发路径不直观。本版本将这些高频编辑动作显式化到界面按钮使平板端在连接外接键盘或使用软键盘时都能快速操作。从源码结构看撤销/重做最终落到 Protyle 的历史栈机制涉及 app/src/protyle 目录下编辑相关模块对撤销记录undo与重做记录redo的入栈、出栈管理Tab 则对应文档块的缩进层级调整与键盘事件的Tab/ShiftTab处理逻辑复用同一套块级操作路径。表情面板支持 ↑/↓ 键选择#9133表情面板此前主要依赖鼠标点选与搜索过滤本版本为其加入了↑/↓ 方向键选择能力。实现集中在 app/src/emoji/index.ts该文件通过keydown事件监听约 L437 起统一处理键盘输入其中对ArrowDown与ArrowUpL501、L519 附近进行响应在面板结果集中移动高亮随后由回车或再次确认完成插入。该文件同时展示出表情面板的完整职责链通过filterEmoji()依据输入框内容过滤并渲染结果依据分类含custom自定义分类分组展示并将最近使用记录维护在window.siyuan.config.editor.emoji数组中通过fetchPost(/api/setting/setEmoji, ...)将最近使用序列持久化到后端设置。因此方向键选择并非孤立功能而是深度嵌入了搜索 → 过滤 → 高亮 → 确认 → 回写最近使用的既有流程。自定义表情支持点击编辑与随字号自适应#9164、#10286本版本对自定义表情做了两处交互增强支持点击编辑自定义表情#9164。此前在文档中使用自定义表情自定义 emoji 实际对应仓库内 app/guide 这样的文档资源或配置中登记的图片资源时无法在插入后直接进入编辑状态。本版本补上了点击即编辑的入口例如文件图标等场景也可复用该对话框能力。调整字体大小后自动调整自定义表情大小#10286。当用户全局调整编辑区字体大小时正文内以字体尺度渲染的自定义表情应当同步缩放否则会出现文字变大而表情不跟随的割裂感。该改动让表情尺寸与字号的联动保持一致。需要说明以上交互改动属于历史版本的行为调整当前仓库已演进至 v3.x相关文件图标与表情对话框的调用入口可在 kernel/api/icon.go图标 API与 app/src/emoji/index.ts表情面板中追踪。其余编辑器细节改进折疊或展開子文件不再跳動#10311文件树文档列表在折叠/展开包含大量子文档的节点时此前可能因文档计数或高度重新计算导致视口跳动本版本对相关计算时机做了稳定化处理。縮放 150% 時支援完整顯示匯出 PDF 預覽#10309在高 DPI / 系统缩放 150% 场景下导出 PDF 的预览窗口此前可能显示不完整本版本修正了预览容器尺寸计算。复制粘贴与剪贴板行为修正复制纯文本不再携带零宽空格#10281这是本版本中最容易从源码层面印证的一项改动。思源笔记在渲染行级元素如列表、代码、引用等时为满足块与光标定位需求会插入零宽空格字符\u200b即Constants.ZWSP定义见 app/src/constants.ts。为避免用户把看起来是纯文本的内容复制到其他应用后出现隐性字符v2.12.7 在复制纯文本的入口做了清洗// app/src/protyle/util/compatibility.ts export const copyPlainText (text: string) { text text.replace(new RegExp(Constants.ZWSP, g), ); // 复制纯文本 时移除所有零宽空格 writeText(text); };该逻辑在 app/src/protyle/util/compatibility.ts 中仍然保留注释与发布说明一致。它说明复制纯文本与复制 HTML是两套不同出口前者会经过零宽空格剥离确保目标端不残留不可见字符后者保留结构信息以用于跨文档粘贴。改进复制数据库表格视图的粘贴效果#10282数据库属性视图表格视图中的单元格复制到外部或内部粘贴时本版本优化了粘贴结果的保真度减少因列内容包含换行/复杂结构导致的串列或错位。这项改进与同版本数据库表格视图文本列换行滚动#10307见下文开发者一节同属对表格视图渲染与复制链路的持续打磨。文件树、插件市场与移动端细节改进文件树新建文件存放位置为空/时自动重置#10305当用户在设置中把新建文件存放位置配置为根目录/时v2.12.7 会将其重设为/Untitled对应 issue #10305。之所以引入该约束是因为若将新文档默认直接建到笔记本根路径用户在大量顶层文档混排的笔记本中会不断产生顶层散落文件后续整理成本较高。将默认位置强制指向/Untitled目录既避免误配置产生的失控感也让新内容默认落入明确的归类目录。这属于配置层防御性修正——在后端逻辑中检测到该配置值非法时回退到安全默认值。停靠栏浮動觸發位置改為動態計算#10295停靠列dock在鼠标靠近屏幕边缘或特定热区时的浮动触发点此前多为固定偏移不同屏幕比例/窗口位置下可能出现明明靠近边缘却不弹出或轻微误触即弹出的问题。本版本将触发位置改为依据窗口当前几何状态动态计算提升悬浮面板唤出的准确度。相关布局逻辑位于 app/src/layout 下停靠栏dock各布局模块中。插件市场下载后启动提示与已下载滚动#10285、#10297针对市场市集使用体验的两处细节改进下載外掛後啟動提示對話框#10285插件安装完成后若该插件要求重启生效界面会给出更明确的对话框提示避免用户困惑于装了为何没生效。改進市集 - 已下載的滾動互動#10297已下载插件列表的分页/滚动加载交互被调整减少滚动到底部时因加载更多内容而出现的跳动或断档。市场前后端实现可分别在 kernel/bazaar插件市场核心逻辑与 app/src/plugin前端插件管理中追踪。移动端滚动与 Android 状态栏#10308、#10278滾動塊元素時不再觸發左右欄面板#10308移动端在文档内纵向滚动较长的块元素如长表格、代码块内的滚动容器时此前可能被误判为水平滑动从而拉出左右侧栏。本版本对滚动方向判定增加了约束只有明确的方向意图才会切换面板。Android 端狀態列顏色異常#10278缺陷修复修复 Android 上沉浸式状态栏在浅色/深色主题切换或键盘弹出后颜色不跟随主题的问题。相关实现可参考 app/src/mobile 下移动端 UI 适配代码与 app/src/config 主题配置项。闪卡相关改动样式、计数与状态机本版本在闪卡Flashcard模块集中处理了三处问题Issue类型改动说明#10296改进退出对焦后显示闪卡样式——复习结束或取消聚焦后确保卡片恢复正确的视觉样式而不停留在编辑中的高亮态#10312缺陷修复复习时切换文件树后刷新计数——闪卡复习界面与文件树联动时若用户在复习过程中切换了文档树位置卡片数量统计需要同步刷新此前存在不刷新的问题#10320缺陷修复卡片为 0 时updateCards返回完成页——当待复习卡片数为 0 时前端更新卡片列表的逻辑会直接进入完成页面状态避免卡在空白或加载态闪卡内核实现位于 kernel/model/flashcard.go前端的复习流程、卡片刷新与状态切换逻辑则分布在 app/src/config 相关闪卡面板模块中可通过updateCards字样在 app/src 内检索对应调用链。开发重构Electron 与 KaTeX 升级升級 Electron v28.2.1#10291桌面端外壳从既有版本升级到 Electron 28.2.1以获得该版本中 Chromium 与 Node.js 运行时层面的安全修复与稳定性改进。Electron 相关配置位于 app/electron主进程main.js以及根目录electron-builder*.yml打包配置中。升級 KaTeX v0.16.9#10321数学公式渲染库升级至 0.16.9属于小版本安全/缺陷跟进。KaTeX 主要服务于行内与块级数学公式渲染在渲染管线中由内核通过 kernel/util/lute.go 配合 Lute 引擎处理 Markdown 数学语法后交给前端 KaTeX 输出。需要说明的是当前仓库已处于更高版本应用版本见 app/package.json桌面壳依赖的 Electron 版本亦已远高于 28.x说明项目在后续版本中持续跟进依赖升级v2.12.7 的这两次升级正是该演进路径上的中间步骤。面向开发者listDocsByPath新增可选参数ignoreMaxListHint#10290这是 v2.12.7 中唯一面向 API 调用者的正式接口变更值得展开。内核实现可直接在当前仓库源码中验证函数体位于 kernel/api/filetree.go。接口语义listDocsByPath用于按路径列出某笔记本notebook下的文档。为保护前端性能内核默认有文档树最大返回数量限制读取自model.Conf.FileTree.MaxListCount。当某目录下文档总数超过该阈值时内核只返回前 N 条并通过消息中心向客户端推送列表过长的提示。ignoreMaxListHint的作用正是抑制这条提示。相关实现L1152-L1164if maxListCount totals { // API listDocsByPath add an optional parameter ignoreMaxListHint ignoreMaxListHintArg : arg[ignoreMaxListHint] if nil ignoreMaxListHintArg || !ignoreMaxListHintArg.(bool) { // 仅当未显式开启 ignoreMaxListHint 时才推送提示 ... util.PushMsgWithApp(app, fmt.Sprintf(model.Conf.Language(48), len(files)), 7000) } }与既有参数的关系注意ignoreMaxListHint与早先引入的maxListCount#7993同样见 kernel/api/filetree.go职责互补maxListCount控制截断阈值。调用方可传更大的值传0或负值则被内核解释为math.MaxInt即不限制来多拿一些结果ignoreMaxListHint只控制提示不影响返回数量。即便目录总数仍超过阈值、返回结果仍被截断只要置true就不会弹出提示。两者都未显式传值时行为与旧版本一致按全局MaxListCount截断并弹提示保证向后兼容。典型调用示例以 REST API 方式调用思源内核默认监听127.0.0.1:6806需携带Authorization: Token token头具体鉴权方式见 kernel/conf/api.go{ notebook: 20210808180117-6v0mkxr, path: /, sort: 0, ignoreMaxListHint: true }当调用方如移动端、第三方脚本在周期轮询目录或明知结果可能超限的场景下置true可避免每条超限请求都触发 7 秒的消息提示干扰若仍需完整列表应同时配合较大的maxListCount。同类参数在内核中并非孤例getTagAPI 也提供了ignoreMaxListHint用于在标签总量超过阈值时跳过提示见 kernel/api/tag.go 与 kernel/model/tag.go 中对Conf.FileTree.MaxListCount的比较。这从侧面印证了该提示机制在文件树与标签两大模块中的通用设计。开发者相关其余改动数据库表格文本列换行滚动#10307另一条列入开发者分类的改动是数据库表格视图中文本列换行滚动的改进长文本单元格支持在列宽受限时按需换行并可滚动查看避免内容被截断或挤压其他列。表格视图的前端渲染逻辑位于 app/src/protyle 中与属性视图表格NodeAttributeView相关的模块内核数据组装可参考 kernel/sql/av_table.go。缺陷修复清单速览除上文已展开说明的 Android 状态栏#10278与闪卡相关修复#10312、#10320外本版本还包括两项值得注意的修复文件图标使用自定义表情时无法打开表情对话框#10280为文档/文件夹设置图标并选用自定义表情时点击图标本应唤起表情选择对话框此前在特定条件下无响应。该对话框入口与自定义表情渲染同属图标/表情模块相关接口见 kernel/api/icon.go。无法删除数据库块前的表格块#10284当普通表格table block紧邻数据库/属性视图块之前时删除操作可能被拦截。该问题与块级删除的事务处理有关块操作链路见 kernel/model/block.go 与 kernel/api/block_op.go。如何获取与追溯该版本v2.12.7 属于 v2.8.4–v2.12.8 发布说明目录app/changelogs/v2.8.4-v2.12.8中的一个里程碑。除本文依据的繁体中文版外该目录通常同时提供简体中文与英文版本完整的历史演进可进一步阅读仓库根目录 CHANGELOG.md。值得留意的是当前仓库主线版本已明显高于 v2.12.7应用版本见 app/package.json阅读本历史发布说明的价值在于理解以下三点日常高频体验表情、复制粘贴、移动端滚动、闪卡是如何被逐轮打磨的ignoreMaxListHint这类向后兼容式新增参数体现了思源 API 的演进风格——默认行为不变、显式传参即可获得新能力Electron/KaTeX 等基础依赖的升级节奏与仓库当前依赖树Electron 主进程与打包配置见 app/electron形成对照可观察项目技术栈的持续迭代路径。对于仍停留在 v2.12.x 的部署可依据官方下载渠道获取对应安装包进行升级对于已升级到 v3.x 的用户本版本绝大多数改动能力均已并入后续主版本无需单独回退安装。小结思源笔记 v2.12.7 以小步快跑的方式完成了编辑器、表情、复制粘贴、文件树、移动端、闪卡、插件市场等多个模块的细节打磨并以listDocsByPath的可选参数ignoreMaxListHint为 API 使用者提供了更可控的超限提示策略。从源码印证角度看零宽空格清理app/src/protyle/util/compatibility.ts、表情面板键盘选择app/src/emoji/index.ts与文件树列表提示抑制kernel/api/filetree.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），仅供参考