1. 项目概述当Notion遇上SolidJS一个高性能的笔记应用诞生了如果你和我一样日常重度依赖Notion来管理知识、项目和零散想法那你一定也体会过它在某些场景下的“力不从心”。比如当文档内容变得非常庞大、嵌套层级很深时页面滚动和编辑的响应偶尔会有些迟滞又或者你希望将Notion那种优雅的块编辑器体验与自己偏爱的某个前端技术栈深度结合打造一个更轻量、更聚焦的私人知识库。这正是“solid-notion”这个项目诞生的背景。它不是一个简单的模仿品而是一个基于现代前端框架SolidJS对Notion核心编辑器体验进行的一次高性能复刻与深度探索。简单来说vincentdchan/solid-notion是一个开源项目它旨在使用SolidJS构建一个高性能、可高度定制的类Notion块编辑器Block-based Editor。项目的核心目标非常明确在保留Notion直观、灵活的块编辑体验的同时利用SolidJS框架的极致性能优势解决复杂文档下的交互流畅性问题并为开发者提供一个清晰、模块化的代码库以便于二次开发和集成到自己的应用中。这个项目适合哪些人呢首先当然是前端开发者尤其是对富文本编辑器实现、状态管理性能优化以及SolidJS框架感兴趣的朋友。通过阅读和运行这个项目的代码你能学到如何从零开始设计一个复杂的、数据驱动的UI组件。其次是那些希望为自己的产品如博客系统、内部Wiki、项目管理工具嵌入一个现代化编辑器的产品经理或全栈开发者。solid-notion提供了一个比从头造轮子更可靠的起点。最后即便是普通用户如果你对Notion的工作原理感到好奇或者想体验一下“未来感”更足的编辑界面这个项目的在线演示也值得一试。2. 核心架构与设计哲学为什么是SolidJS在深入代码之前我们必须先理解项目选型背后的“为什么”。前端框架的选择往往决定了应用的基因。solid-notion没有选择更流行的React或Vue而是押注于SolidJS这背后有深刻的技术考量。2.1 SolidJS的“反应式”魔法与性能优势SolidJS的核心卖点是其细粒度的响应式系统。与React的虚拟DOMVirtual DOMdiff算法不同SolidJS在编译时就能分析出状态与UI之间的依赖关系。它直接操作真实的DOM当状态变化时只更新依赖该状态的具体DOM节点而不是整个组件树甚至虚拟DOM树。我们可以用一个生活化的类比来理解假设一个页面是一个复杂的仪表盘有速度表、转速表、油量表等。React的方式是任何一个数据变化比如速度它都会重新计算整个仪表盘的“设计图”虚拟DOM然后和旧的设计图对比找出需要重新喷漆的部分DOM更新。而SolidJS的方式是在制造之初就用一根无形的线直接把“速度数据”和“速度表的指针”连了起来。当速度数据变化时直接拉动这根线指针就动了其他表盘完全不受影响。这种机制带来的性能优势在编辑器这种高频、局部更新的场景下是巨大的。在Notion式的编辑器中你输入文字、切换标题格式、拖拽块的位置都是非常局部的操作。使用SolidJS这些操作几乎可以瞬间响应因为框架精确地知道需要更新哪几个字符的显示或哪个div的位置避免了不必要的计算和渲染。2.2 项目整体架构拆解solid-notion的代码结构清晰地反映了其模块化设计的思想。虽然项目在不断迭代但其核心架构通常包含以下几个层次数据层Model定义“块”Block的数据结构。一个块可能是一个段落、一个标题、一个待办列表、一个引用块等等。这个结构通常是树形的因为块可以嵌套例如一个列表项里可以包含多个段落。数据层是纯JavaScript对象不依赖任何UI框架这保证了核心逻辑的可测试性和可移植性。状态管理层State/Store管理所有块的集合、当前选中的块、光标位置等全局状态。这里会大量使用SolidJS提供的createStore,createSignal等原语来创建响应式数据。状态的变化会自动驱动UI更新。编辑器核心层Core这是最复杂的部分负责处理所有编辑交互。包括命令系统Commands对应键盘快捷键或菜单操作如“加粗”、“转换为标题”、“缩进”等。每个命令都是一个纯函数接收当前状态返回新的状态。选区与光标管理Selection监听和操作浏览器的Selection和RangeAPI处理文字选中、光标移动等。这部分需要精细地处理contenteditable元素的种种怪异行为。键盘事件处理拦截并处理Enter,Backspace,Tab等关键按键将其转化为对数据结构的操作如拆分块、删除块、调整层级。UI组件层Components使用SolidJS的JSX语法将“块数据”渲染为对应的UI组件。例如一个{ type: heading, level: 1, content: ... }的数据会被渲染为h1.../h1。这一层也包含工具栏、侧边菜单等交互界面。序列化与反序列化负责将内存中的块树结构转换为可以存储的格式如JSON、Markdown、HTML以及从这些格式中还原出块树。这是实现导入导出、协同编辑需要OT/CRDT算法这是更高级的话题的基础。这种分层架构使得各个部分的职责清晰开发者可以相对独立地修改UI样式、增加新的块类型或者替换底层的状态管理策略。注意理解这个架构图是理解项目代码的关键。当你克隆代码库后不要急于直接运行先花时间浏览src目录下的文件夹结构对照上述层次找到对应的文件这能帮你快速建立心智模型。3. 核心实现细节打造一个“块”的世界让我们深入到最核心的“块”Block的实现中。这是整个编辑器的基石。3.1 块数据结构的定义一个块至少需要包含以下信息interface Block { id: string; // 唯一标识符通常使用UUID或纳秒时间戳 type: string; // 块类型如 paragraph, heading1, bullet_list, todo... content: string; // 块的文本内容对于简单文本块 // 或者更复杂的结构用于支持行内格式如加粗、斜体、链接 // content: Array{ text: string; bold?: boolean; italic?: boolean; link?: string }; children: Block[]; // 子块用于实现嵌套如列表项下的子列表 properties?: Recordstring, any; // 扩展属性如待办事项的checked状态 parentId?: string | null; // 父块ID用于快速定位层级关系 }在solid-notion中状态管理很可能使用一个Mapstring, Block以id为键来存储所有块再配合一个rootId来指向根节点或顶级块的集合。这种扁平化存储将所有块放在一个Map里配合索引parentId比纯粹的深嵌套树在更新时性能更好因为SolidJS可以更精确地追踪单个块的变化。3.2 块渲染与动态组件如何根据block.type动态渲染不同的UI组件SolidJS提供了Dynamic组件或者更简单的条件渲染来实现。// 一个简化的块渲染器组件 const BlockRenderer ({ block }) { return ( div>// 简化的快捷键处理逻辑 const handleKeyDown (e) { const { key, ctrlKey, metaKey, shiftKey } e; const isMod ctrlKey || metaKey; // 兼容Mac的Cmd键 if (key Enter) { e.preventDefault(); handleEnter(); // 处理回车拆分块或创建新块 } else if (key Backspace) { if (/* 光标在块开头 */) { e.preventDefault(); handleBackspaceAtStart(); // 可能合并到上一个块 } } else if (key Tab) { e.preventDefault(); // 非常重要防止Tab键切换焦点 if (shiftKey) { outdentCurrentBlock(); } else { indentCurrentBlock(); } } else if (isMod key b) { e.preventDefault(); toggleBold(); // 切换加粗格式 } // ... 更多快捷键 };实操心得处理Enter和Backspace键的逻辑是编辑器体验的“灵魂”。你需要考虑数十种边界情况在空块中按回车是删除它还是创建新空块在列表项末尾按回车是创建同级新项还是跳出列表在标题块中按回车是创建普通段落还是继承标题等级这些逻辑的完善程度直接决定了编辑器是否“跟手”。建议参考成熟编辑器如Prosemirror, Slate的默认行为它们已经经过了大量用户实践的检验。5. 性能优化实战让编辑器如丝般顺滑选择了SolidJS我们已经站在了性能的起跑线前方。但要让一个功能复杂的编辑器真正流畅还需要在以下几个方面下功夫5.1 虚拟化列表渲染当文档包含成千上万个块时一次性渲染所有DOM节点会导致严重的性能问题首次加载慢滚动卡顿。解决方案是虚拟滚动只渲染视口Viewport及其附近的可视区域内的块。实现原理计算编辑器容器的滚动位置scrollTop。根据每个块的预估高度或精确测量出的高度计算出当前哪些块落在可视区域内。只将这部分块渲染为真实的DOM元素。对于视口外的块用一个具有正确总高度的占位div来撑开滚动条保持滚动体验真实。SolidJS社区有solid-virtual这样的虚拟滚动库但集成到块编辑器的树形结构中需要一些适配工作因为你需要计算整个块树的“扁平化”高度列表。5.2 防抖与节流编辑器内的一些操作不需要实时响应。例如自动保存应在用户停止输入一段时间如500ms后触发而不是每次按键都保存。这使用防抖Debounce。语法高亮或拼写检查对于复杂的计算可以节流Throttle其执行频率比如每200ms检查一次。滚动时的高亮或位置计算滚动事件触发非常频繁必须节流处理。SolidJS的createMemo和createEffect本身具有依赖追踪和批量更新的能力但结合setTimeout或requestAnimationFrame进行手动防抖节流仍然是必要的。5.3 不可变数据与精细更新这是发挥SolidJS优势的关键。确保你的块状态更新总是遵循不可变Immutable原则。这意味着不是直接修改一个块对象而是创建一个新的对象或新的Map/Array。// 不好的做法直接修改 blocksMap.get(blockId).content newContent; // SolidJS可能无法检测到变化 // 好的做法创建新的引用 setBlocksMap(prev { const newMap new Map(prev); newMap.set(blockId, { ...prev.get(blockId), content: newContent }); return newMap; }); // 或者使用SolidJS的store API它内部处理了不可变更新 setBlocks(blockId, content, newContent);当数据不可变时SolidJS可以更高效地进行依赖比较。如果一个子组件只依赖于blockId对应的那个块对象那么当其他块变化时这个组件根本不会重新执行re-render实现了极致的更新效率。5.4 测量与监控性能优化不能靠猜。使用浏览器开发者工具的Performance面板录制一段编辑操作快速输入、频繁拖拽观察火焰图Flame Chart中哪些函数耗时最长。使用Memory面板检查是否有内存泄漏比如事件监听器未移除、DOM节点未清理。对于编辑器一个关键的监控指标是输入延迟Input Latency即从按键到字符出现在屏幕上的时间。理想情况下应低于16ms对应60Hz刷新率。如果发现延迟过高就需要定位是JavaScript执行过长Long Task还是DOM更新或样式计算太慢。6. 扩展与定制打造属于你自己的编辑器solid-notion作为一个开源项目其价值不仅在于它本身更在于它提供的可扩展性。你可以通过以下几种方式将其改造成适合自己需求的样子。6.1 添加自定义块类型假设你想添加一个“代码块”类型支持语法高亮。扩展数据模型在Block类型定义中增加type: code并可能需要额外的properties如language: javascript。创建UI组件新建一个CodeBlock.jsx组件。它接收block作为prop渲染一个precode结构。可以使用highlight.js或Prism.js库来实现语法高亮。高亮操作应在createEffect中执行并依赖于block.content和block.properties.language的变化。注册块类型在块渲染器的映射表或Switch语句中添加对新类型的支持。添加快捷键/工具栏修改快捷键系统或工具栏增加一个插入代码块的命令如输入/code或点击工具栏按钮。这个命令会调用状态更新函数在当前位置插入一个类型为code的新块。6.2 集成第三方工具公式编辑集成MathJax或KaTeX添加一个equation块类型渲染时用它们解析LaTeX字符串。图表绘制可以集成Mermaid添加一个mermaid块类型内容是一段Mermaid文本渲染时用Mermaid生成SVG图表。文件上传在image或file块类型中集成到云存储服务如AWS S3、Cloudinary或后端API的上传逻辑。处理上传状态上传中、成功、失败的UI反馈。6.3 主题与样式系统为了让编辑器融入不同产品样式系统必须灵活。solid-notion应该使用CSS变量Custom Properties来定义颜色、字体、间距、圆角等设计令牌Design Tokens。/* 定义变量 */ .editor-container { --bg-primary: white; --text-primary: #333; --border-color: #ddd; --block-hover-bg: #f5f5f5; } /* 组件使用变量 */ .block { background-color: var(--bg-primary); color: var(--text-primary); border: 1px solid var(--border-color); } .block:hover { background-color: var(--block-hover-bg); }这样用户只需覆盖这些CSS变量就能轻松实现深色模式或匹配品牌色的主题切换而无需深入修改每个组件的具体样式。6.4 与后端对接持久化与协同编辑器本身是前端但数据最终需要保存。你需要设计一个与后端通信的层。序列化定期或在特定时机如离开页面、手动保存将内存中的块树状态blocksMap序列化为一个更紧凑的JSON结构。API设计定义POST /api/document/save和GET /api/document/:id等接口。保存时发送序列化后的数据加载时接收数据并反序列化初始化前端状态。冲突解决进阶如果支持多人实时协同编辑问题将变得极其复杂。你需要引入操作转换OT或无冲突复制数据类型CRDT算法。这通常意味着前端的每个操作如“在位置X插入字符‘A’”都需要被记录、编号、发送到后端服务器进行转换再广播给其他用户。这是一个非常专业的领域通常建议使用现成的协同库如Yjs它可以与SolidJS集成并自动处理网络同步和冲突合并。7. 常见问题与调试技巧实录在开发和集成solid-notion这类复杂编辑器时你一定会遇到各种“坑”。以下是我从实践中总结的一些典型问题及其解决方法。7.1 光标跳动或消失这是富文本编辑器中最常见也最令人头疼的问题。症状输入文字后光标突然跳回行首或消失执行某个命令如加粗后输入焦点丢失。根本原因在React/SolidJS等框架中组件的重新渲染可能导致包含contenteditable的DOM节点被替换或更新浏览器原生的选区Selection信息会因此丢失。解决方案保存与恢复选区在执行任何可能导致DOM更新的操作如状态更新之前先保存当前选区的anchorNode、anchorOffset、focusNode、focusOffset。操作完成后在下一个微任务queueMicrotask或createEffect中尝试使用document.getSelection()和RangeAPI将光标恢复到之前的位置。使用受控组件模式如果采用“混合编辑”模型用隐藏的textarea接收输入则焦点始终在可控的输入元素上可以避免此问题。为可编辑元素添加key如果必须使用contenteditable确保其所在的SolidJS组件有一个稳定的key或者使用div ref{el (this.editableEl el)}直接引用DOM元素避免组件销毁重建。7.2 中文输入法IME兼容性问题症状在输入中文时拼音候选词显示在错误的位置或者输入过程中触发了一些快捷键命令。原因输入法组合输入期间会触发多个keydown、keypress、compositionstart、compositionupdate、compositionend事件。如果在compositionstart到compositionend期间处理了keydown事件就会干扰输入法。解决方案在编辑器根元素上监听compositionstart和compositionend事件设置一个标志位如isComposing。在处理keydown事件时先检查isComposing是否为true如果是则跳过命令处理只做最基本的更新或者完全交给浏览器处理。7.3 粘贴内容格式混乱症状从网页或Word中复制内容粘贴到编辑器格式错乱带了大量不需要的HTML标签和样式。解决方案拦截paste事件。e.preventDefault()阻止默认粘贴行为。从e.clipboardData中获取纯文本getData(text/plain)和HTMLgetData(text/html)。编写一个“粘贴处理器”Paste Parser。这是一个复杂的模块它需要解析粘贴进来的HTML清理掉无用的标签和样式可以使用DOMParser。将清理后的DOM结构转换为你自己的块数据结构。例如将h1转换为{type: heading1}将ulli.../li/ul转换为{type: bullet_list, children: [...]}。将转换后的块数据插入到当前光标位置。对于从Word粘贴的特殊情况可能需要处理mso-等MS特有的样式。可以寻找现成的库如prosemirror-transform中的DOMParser规则集作为参考或直接使用。7.4 移动端触摸交互支持不佳症状在手机或平板上拖拽不灵敏长按菜单不出现虚拟键盘弹出后界面布局错乱。解决方案拖拽将基于pointer事件的拖拽逻辑确保也正确处理touchstart,touchmove,touchend事件并调用e.preventDefault()防止页面滚动。选区移动端上通过长按来启动文本选区。你需要确保可编辑区域监听contextmenu事件在移动端可能由长按触发并可能提供一个自定义的放大镜Magnifier组件来帮助精确选择。虚拟键盘使用CSS的media查询和env(safe-area-inset-bottom)来调整编辑器底部间距避免键盘遮挡。监听window.visualViewport的resize事件动态调整编辑器容器的高度或滚动位置。7.5 性能问题排查清单当编辑器变慢时按以下顺序检查是否渲染了过多DOM节点检查开发者工具Elements面板是否需要虚拟滚动。是否有不必要的大型计算在每次渲染时运行使用createMemo包裹计算密集型操作确保其只在依赖项变化时重新计算。事件监听器是否未正确清理在onCleanupSolidJS的生命周期函数中移除所有手动添加的全局事件监听器、定时器。CSS是否导致重排/重绘避免频繁修改会触发布局Layout的CSS属性如width,height,top,left使用transform替代。使用will-change属性提示浏览器。内存是否泄漏在Performance面板进行内存快照对比查看Detached DOM tree是否持续增长这通常意味着被移除的DOM节点仍被JavaScript对象引用。开发一个像solid-notion这样的块编辑器是一个充满挑战但也极具成就感的过程。它要求你深入理解前端框架、浏览器API、数据结构和UI交互的方方面面。从克隆项目、运行示例开始尝试修改一个块的外观添加一个简单的快捷键再到实现一个全新的块类型每一步都能让你对现代Web应用的复杂性有更深的认识。这个项目不仅是一个工具更是一个绝佳的学习平台。当你最终看到自己定制后的编辑器流畅运行那种感觉就像亲手打造了一件称手的兵器。
基于SolidJS构建高性能块编辑器：架构设计与实现解析
1. 项目概述当Notion遇上SolidJS一个高性能的笔记应用诞生了如果你和我一样日常重度依赖Notion来管理知识、项目和零散想法那你一定也体会过它在某些场景下的“力不从心”。比如当文档内容变得非常庞大、嵌套层级很深时页面滚动和编辑的响应偶尔会有些迟滞又或者你希望将Notion那种优雅的块编辑器体验与自己偏爱的某个前端技术栈深度结合打造一个更轻量、更聚焦的私人知识库。这正是“solid-notion”这个项目诞生的背景。它不是一个简单的模仿品而是一个基于现代前端框架SolidJS对Notion核心编辑器体验进行的一次高性能复刻与深度探索。简单来说vincentdchan/solid-notion是一个开源项目它旨在使用SolidJS构建一个高性能、可高度定制的类Notion块编辑器Block-based Editor。项目的核心目标非常明确在保留Notion直观、灵活的块编辑体验的同时利用SolidJS框架的极致性能优势解决复杂文档下的交互流畅性问题并为开发者提供一个清晰、模块化的代码库以便于二次开发和集成到自己的应用中。这个项目适合哪些人呢首先当然是前端开发者尤其是对富文本编辑器实现、状态管理性能优化以及SolidJS框架感兴趣的朋友。通过阅读和运行这个项目的代码你能学到如何从零开始设计一个复杂的、数据驱动的UI组件。其次是那些希望为自己的产品如博客系统、内部Wiki、项目管理工具嵌入一个现代化编辑器的产品经理或全栈开发者。solid-notion提供了一个比从头造轮子更可靠的起点。最后即便是普通用户如果你对Notion的工作原理感到好奇或者想体验一下“未来感”更足的编辑界面这个项目的在线演示也值得一试。2. 核心架构与设计哲学为什么是SolidJS在深入代码之前我们必须先理解项目选型背后的“为什么”。前端框架的选择往往决定了应用的基因。solid-notion没有选择更流行的React或Vue而是押注于SolidJS这背后有深刻的技术考量。2.1 SolidJS的“反应式”魔法与性能优势SolidJS的核心卖点是其细粒度的响应式系统。与React的虚拟DOMVirtual DOMdiff算法不同SolidJS在编译时就能分析出状态与UI之间的依赖关系。它直接操作真实的DOM当状态变化时只更新依赖该状态的具体DOM节点而不是整个组件树甚至虚拟DOM树。我们可以用一个生活化的类比来理解假设一个页面是一个复杂的仪表盘有速度表、转速表、油量表等。React的方式是任何一个数据变化比如速度它都会重新计算整个仪表盘的“设计图”虚拟DOM然后和旧的设计图对比找出需要重新喷漆的部分DOM更新。而SolidJS的方式是在制造之初就用一根无形的线直接把“速度数据”和“速度表的指针”连了起来。当速度数据变化时直接拉动这根线指针就动了其他表盘完全不受影响。这种机制带来的性能优势在编辑器这种高频、局部更新的场景下是巨大的。在Notion式的编辑器中你输入文字、切换标题格式、拖拽块的位置都是非常局部的操作。使用SolidJS这些操作几乎可以瞬间响应因为框架精确地知道需要更新哪几个字符的显示或哪个div的位置避免了不必要的计算和渲染。2.2 项目整体架构拆解solid-notion的代码结构清晰地反映了其模块化设计的思想。虽然项目在不断迭代但其核心架构通常包含以下几个层次数据层Model定义“块”Block的数据结构。一个块可能是一个段落、一个标题、一个待办列表、一个引用块等等。这个结构通常是树形的因为块可以嵌套例如一个列表项里可以包含多个段落。数据层是纯JavaScript对象不依赖任何UI框架这保证了核心逻辑的可测试性和可移植性。状态管理层State/Store管理所有块的集合、当前选中的块、光标位置等全局状态。这里会大量使用SolidJS提供的createStore,createSignal等原语来创建响应式数据。状态的变化会自动驱动UI更新。编辑器核心层Core这是最复杂的部分负责处理所有编辑交互。包括命令系统Commands对应键盘快捷键或菜单操作如“加粗”、“转换为标题”、“缩进”等。每个命令都是一个纯函数接收当前状态返回新的状态。选区与光标管理Selection监听和操作浏览器的Selection和RangeAPI处理文字选中、光标移动等。这部分需要精细地处理contenteditable元素的种种怪异行为。键盘事件处理拦截并处理Enter,Backspace,Tab等关键按键将其转化为对数据结构的操作如拆分块、删除块、调整层级。UI组件层Components使用SolidJS的JSX语法将“块数据”渲染为对应的UI组件。例如一个{ type: heading, level: 1, content: ... }的数据会被渲染为h1.../h1。这一层也包含工具栏、侧边菜单等交互界面。序列化与反序列化负责将内存中的块树结构转换为可以存储的格式如JSON、Markdown、HTML以及从这些格式中还原出块树。这是实现导入导出、协同编辑需要OT/CRDT算法这是更高级的话题的基础。这种分层架构使得各个部分的职责清晰开发者可以相对独立地修改UI样式、增加新的块类型或者替换底层的状态管理策略。注意理解这个架构图是理解项目代码的关键。当你克隆代码库后不要急于直接运行先花时间浏览src目录下的文件夹结构对照上述层次找到对应的文件这能帮你快速建立心智模型。3. 核心实现细节打造一个“块”的世界让我们深入到最核心的“块”Block的实现中。这是整个编辑器的基石。3.1 块数据结构的定义一个块至少需要包含以下信息interface Block { id: string; // 唯一标识符通常使用UUID或纳秒时间戳 type: string; // 块类型如 paragraph, heading1, bullet_list, todo... content: string; // 块的文本内容对于简单文本块 // 或者更复杂的结构用于支持行内格式如加粗、斜体、链接 // content: Array{ text: string; bold?: boolean; italic?: boolean; link?: string }; children: Block[]; // 子块用于实现嵌套如列表项下的子列表 properties?: Recordstring, any; // 扩展属性如待办事项的checked状态 parentId?: string | null; // 父块ID用于快速定位层级关系 }在solid-notion中状态管理很可能使用一个Mapstring, Block以id为键来存储所有块再配合一个rootId来指向根节点或顶级块的集合。这种扁平化存储将所有块放在一个Map里配合索引parentId比纯粹的深嵌套树在更新时性能更好因为SolidJS可以更精确地追踪单个块的变化。3.2 块渲染与动态组件如何根据block.type动态渲染不同的UI组件SolidJS提供了Dynamic组件或者更简单的条件渲染来实现。// 一个简化的块渲染器组件 const BlockRenderer ({ block }) { return ( div>// 简化的快捷键处理逻辑 const handleKeyDown (e) { const { key, ctrlKey, metaKey, shiftKey } e; const isMod ctrlKey || metaKey; // 兼容Mac的Cmd键 if (key Enter) { e.preventDefault(); handleEnter(); // 处理回车拆分块或创建新块 } else if (key Backspace) { if (/* 光标在块开头 */) { e.preventDefault(); handleBackspaceAtStart(); // 可能合并到上一个块 } } else if (key Tab) { e.preventDefault(); // 非常重要防止Tab键切换焦点 if (shiftKey) { outdentCurrentBlock(); } else { indentCurrentBlock(); } } else if (isMod key b) { e.preventDefault(); toggleBold(); // 切换加粗格式 } // ... 更多快捷键 };实操心得处理Enter和Backspace键的逻辑是编辑器体验的“灵魂”。你需要考虑数十种边界情况在空块中按回车是删除它还是创建新空块在列表项末尾按回车是创建同级新项还是跳出列表在标题块中按回车是创建普通段落还是继承标题等级这些逻辑的完善程度直接决定了编辑器是否“跟手”。建议参考成熟编辑器如Prosemirror, Slate的默认行为它们已经经过了大量用户实践的检验。5. 性能优化实战让编辑器如丝般顺滑选择了SolidJS我们已经站在了性能的起跑线前方。但要让一个功能复杂的编辑器真正流畅还需要在以下几个方面下功夫5.1 虚拟化列表渲染当文档包含成千上万个块时一次性渲染所有DOM节点会导致严重的性能问题首次加载慢滚动卡顿。解决方案是虚拟滚动只渲染视口Viewport及其附近的可视区域内的块。实现原理计算编辑器容器的滚动位置scrollTop。根据每个块的预估高度或精确测量出的高度计算出当前哪些块落在可视区域内。只将这部分块渲染为真实的DOM元素。对于视口外的块用一个具有正确总高度的占位div来撑开滚动条保持滚动体验真实。SolidJS社区有solid-virtual这样的虚拟滚动库但集成到块编辑器的树形结构中需要一些适配工作因为你需要计算整个块树的“扁平化”高度列表。5.2 防抖与节流编辑器内的一些操作不需要实时响应。例如自动保存应在用户停止输入一段时间如500ms后触发而不是每次按键都保存。这使用防抖Debounce。语法高亮或拼写检查对于复杂的计算可以节流Throttle其执行频率比如每200ms检查一次。滚动时的高亮或位置计算滚动事件触发非常频繁必须节流处理。SolidJS的createMemo和createEffect本身具有依赖追踪和批量更新的能力但结合setTimeout或requestAnimationFrame进行手动防抖节流仍然是必要的。5.3 不可变数据与精细更新这是发挥SolidJS优势的关键。确保你的块状态更新总是遵循不可变Immutable原则。这意味着不是直接修改一个块对象而是创建一个新的对象或新的Map/Array。// 不好的做法直接修改 blocksMap.get(blockId).content newContent; // SolidJS可能无法检测到变化 // 好的做法创建新的引用 setBlocksMap(prev { const newMap new Map(prev); newMap.set(blockId, { ...prev.get(blockId), content: newContent }); return newMap; }); // 或者使用SolidJS的store API它内部处理了不可变更新 setBlocks(blockId, content, newContent);当数据不可变时SolidJS可以更高效地进行依赖比较。如果一个子组件只依赖于blockId对应的那个块对象那么当其他块变化时这个组件根本不会重新执行re-render实现了极致的更新效率。5.4 测量与监控性能优化不能靠猜。使用浏览器开发者工具的Performance面板录制一段编辑操作快速输入、频繁拖拽观察火焰图Flame Chart中哪些函数耗时最长。使用Memory面板检查是否有内存泄漏比如事件监听器未移除、DOM节点未清理。对于编辑器一个关键的监控指标是输入延迟Input Latency即从按键到字符出现在屏幕上的时间。理想情况下应低于16ms对应60Hz刷新率。如果发现延迟过高就需要定位是JavaScript执行过长Long Task还是DOM更新或样式计算太慢。6. 扩展与定制打造属于你自己的编辑器solid-notion作为一个开源项目其价值不仅在于它本身更在于它提供的可扩展性。你可以通过以下几种方式将其改造成适合自己需求的样子。6.1 添加自定义块类型假设你想添加一个“代码块”类型支持语法高亮。扩展数据模型在Block类型定义中增加type: code并可能需要额外的properties如language: javascript。创建UI组件新建一个CodeBlock.jsx组件。它接收block作为prop渲染一个precode结构。可以使用highlight.js或Prism.js库来实现语法高亮。高亮操作应在createEffect中执行并依赖于block.content和block.properties.language的变化。注册块类型在块渲染器的映射表或Switch语句中添加对新类型的支持。添加快捷键/工具栏修改快捷键系统或工具栏增加一个插入代码块的命令如输入/code或点击工具栏按钮。这个命令会调用状态更新函数在当前位置插入一个类型为code的新块。6.2 集成第三方工具公式编辑集成MathJax或KaTeX添加一个equation块类型渲染时用它们解析LaTeX字符串。图表绘制可以集成Mermaid添加一个mermaid块类型内容是一段Mermaid文本渲染时用Mermaid生成SVG图表。文件上传在image或file块类型中集成到云存储服务如AWS S3、Cloudinary或后端API的上传逻辑。处理上传状态上传中、成功、失败的UI反馈。6.3 主题与样式系统为了让编辑器融入不同产品样式系统必须灵活。solid-notion应该使用CSS变量Custom Properties来定义颜色、字体、间距、圆角等设计令牌Design Tokens。/* 定义变量 */ .editor-container { --bg-primary: white; --text-primary: #333; --border-color: #ddd; --block-hover-bg: #f5f5f5; } /* 组件使用变量 */ .block { background-color: var(--bg-primary); color: var(--text-primary); border: 1px solid var(--border-color); } .block:hover { background-color: var(--block-hover-bg); }这样用户只需覆盖这些CSS变量就能轻松实现深色模式或匹配品牌色的主题切换而无需深入修改每个组件的具体样式。6.4 与后端对接持久化与协同编辑器本身是前端但数据最终需要保存。你需要设计一个与后端通信的层。序列化定期或在特定时机如离开页面、手动保存将内存中的块树状态blocksMap序列化为一个更紧凑的JSON结构。API设计定义POST /api/document/save和GET /api/document/:id等接口。保存时发送序列化后的数据加载时接收数据并反序列化初始化前端状态。冲突解决进阶如果支持多人实时协同编辑问题将变得极其复杂。你需要引入操作转换OT或无冲突复制数据类型CRDT算法。这通常意味着前端的每个操作如“在位置X插入字符‘A’”都需要被记录、编号、发送到后端服务器进行转换再广播给其他用户。这是一个非常专业的领域通常建议使用现成的协同库如Yjs它可以与SolidJS集成并自动处理网络同步和冲突合并。7. 常见问题与调试技巧实录在开发和集成solid-notion这类复杂编辑器时你一定会遇到各种“坑”。以下是我从实践中总结的一些典型问题及其解决方法。7.1 光标跳动或消失这是富文本编辑器中最常见也最令人头疼的问题。症状输入文字后光标突然跳回行首或消失执行某个命令如加粗后输入焦点丢失。根本原因在React/SolidJS等框架中组件的重新渲染可能导致包含contenteditable的DOM节点被替换或更新浏览器原生的选区Selection信息会因此丢失。解决方案保存与恢复选区在执行任何可能导致DOM更新的操作如状态更新之前先保存当前选区的anchorNode、anchorOffset、focusNode、focusOffset。操作完成后在下一个微任务queueMicrotask或createEffect中尝试使用document.getSelection()和RangeAPI将光标恢复到之前的位置。使用受控组件模式如果采用“混合编辑”模型用隐藏的textarea接收输入则焦点始终在可控的输入元素上可以避免此问题。为可编辑元素添加key如果必须使用contenteditable确保其所在的SolidJS组件有一个稳定的key或者使用div ref{el (this.editableEl el)}直接引用DOM元素避免组件销毁重建。7.2 中文输入法IME兼容性问题症状在输入中文时拼音候选词显示在错误的位置或者输入过程中触发了一些快捷键命令。原因输入法组合输入期间会触发多个keydown、keypress、compositionstart、compositionupdate、compositionend事件。如果在compositionstart到compositionend期间处理了keydown事件就会干扰输入法。解决方案在编辑器根元素上监听compositionstart和compositionend事件设置一个标志位如isComposing。在处理keydown事件时先检查isComposing是否为true如果是则跳过命令处理只做最基本的更新或者完全交给浏览器处理。7.3 粘贴内容格式混乱症状从网页或Word中复制内容粘贴到编辑器格式错乱带了大量不需要的HTML标签和样式。解决方案拦截paste事件。e.preventDefault()阻止默认粘贴行为。从e.clipboardData中获取纯文本getData(text/plain)和HTMLgetData(text/html)。编写一个“粘贴处理器”Paste Parser。这是一个复杂的模块它需要解析粘贴进来的HTML清理掉无用的标签和样式可以使用DOMParser。将清理后的DOM结构转换为你自己的块数据结构。例如将h1转换为{type: heading1}将ulli.../li/ul转换为{type: bullet_list, children: [...]}。将转换后的块数据插入到当前光标位置。对于从Word粘贴的特殊情况可能需要处理mso-等MS特有的样式。可以寻找现成的库如prosemirror-transform中的DOMParser规则集作为参考或直接使用。7.4 移动端触摸交互支持不佳症状在手机或平板上拖拽不灵敏长按菜单不出现虚拟键盘弹出后界面布局错乱。解决方案拖拽将基于pointer事件的拖拽逻辑确保也正确处理touchstart,touchmove,touchend事件并调用e.preventDefault()防止页面滚动。选区移动端上通过长按来启动文本选区。你需要确保可编辑区域监听contextmenu事件在移动端可能由长按触发并可能提供一个自定义的放大镜Magnifier组件来帮助精确选择。虚拟键盘使用CSS的media查询和env(safe-area-inset-bottom)来调整编辑器底部间距避免键盘遮挡。监听window.visualViewport的resize事件动态调整编辑器容器的高度或滚动位置。7.5 性能问题排查清单当编辑器变慢时按以下顺序检查是否渲染了过多DOM节点检查开发者工具Elements面板是否需要虚拟滚动。是否有不必要的大型计算在每次渲染时运行使用createMemo包裹计算密集型操作确保其只在依赖项变化时重新计算。事件监听器是否未正确清理在onCleanupSolidJS的生命周期函数中移除所有手动添加的全局事件监听器、定时器。CSS是否导致重排/重绘避免频繁修改会触发布局Layout的CSS属性如width,height,top,left使用transform替代。使用will-change属性提示浏览器。内存是否泄漏在Performance面板进行内存快照对比查看Detached DOM tree是否持续增长这通常意味着被移除的DOM节点仍被JavaScript对象引用。开发一个像solid-notion这样的块编辑器是一个充满挑战但也极具成就感的过程。它要求你深入理解前端框架、浏览器API、数据结构和UI交互的方方面面。从克隆项目、运行示例开始尝试修改一个块的外观添加一个简单的快捷键再到实现一个全新的块类型每一步都能让你对现代Web应用的复杂性有更深的认识。这个项目不仅是一个工具更是一个绝佳的学习平台。当你最终看到自己定制后的编辑器流畅运行那种感觉就像亲手打造了一件称手的兵器。
