Tolaria 富文本编辑器输入变换统一架构解析共享 beforeinput 执行管线ADR-0137 实践指南【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria导读本文以 Tolaria 仓库中的架构决策记录 docs/adr/0137-shared-rich-editor-input-transforms.md 为主体深入剖析 Tolaria 富文本BlockNote/ProseMirror编辑器中 Markdown 风格输入变换的统一执行管线。你将理解箭头连字-→ 箭头符号、行内数学公式$...$、高亮标记、维基链接[[...]]等输入特性为何要收敛到一个共享的beforeinput执行路径各自的语法匹配如何保持独立以及统一后的错误恢复、IME 组合输入防护、事务派发策略在源码层面是如何落地的。读完后你将掌握这套共享执行壳 特性自有匹配器的扩展模式可直接用于自己的 BlockNote/ProseMirror 编辑器项目。一、背景多个 Markdown 便利特性如何挤进编辑器Tolaria 的富文本编辑器基于 BlockNote其底层是 ProseMirror并内置了多种 Markdown 风格的输入便利键入的 ASCII 箭头如-自动变为连字/箭头字符完成的行内数学语法自动收敛为 math 节点公式节点完成highlight语法自动收敛为持久的 highlight 标记键入]]完成维基链接语法时收敛为 wikilink 节点。这些特性最初是逐个以独立的beforeinput扩展增量添加的见 docs/adr/0137-shared-rich-editor-input-transforms.md 的 Context 部分。每个扩展都重复了同一套生命周期工作读取实时 ProseMirrorEditorView跳过 IME 组合输入composition阶段守卫过期/已销毁的 view派发dispatch事务仅在变换成功后才阻止原生输入preventDefault恢复已知的 BlockNote/ProseMirror 变换失败。语法匹配器各不相同但执行外壳高度相似。结果是每新增一个 Markdown 便利特性都面临一套略有差异的边界情况策略边缘行为容易出现分歧。二、决策一个共享的 beforeinput 执行路径ADR-0137 的决策非常明确Tolaria 将富文本编辑器的 Markdown 输入变换路由到同一条共享beforeinput执行路径。该决策在源码中的落点有三处核心文件均在 src/components 下文件职责richEditorInputTransform.ts拥有公共生命周期、事务派发与可恢复错误行为是执行壳特性文件arrowLigaturesExtension.ts / mathInputExtension.ts / markdownHighlightInputExtension.ts / wikilinkInputExtension.ts只暴露小型的 transform 对象决定当前输入事件是否应产生事务richEditorInputTransformExtension.ts组合主编辑器与隐藏编辑器探针使用的 Markdown 变换集合2.1 共享执行壳richEditorInputTransform.ts该文件定义了统一的变换契约。核心类型如下见 richEditorInputTransform.tsexport interface RichEditorInputTransformContext { view: RichEditorInputView } export interface RichEditorInputTransformResult { ignoreDispatchError?: boolean onDispatchError?: (error: unknown) void preventDefault?: boolean transaction: RichEditorInputTransaction } export interface RichEditorInputTransform { handleBeforeInput: ( event: InputEvent, context: RichEditorInputTransformContext ) RichEditorInputTransformResult | null reset?: () void }关键点返回null表示本变换不处理此输入执行壳会继续尝试下一个变换返回RichEditorInputTransformResult表示变换成功附带一个待派发的 ProseMirror 事务preventDefault控制是否阻止浏览器的原生输入只有在变换成功后才阻止避免吞掉普通输入ignoreDispatchError与onDispatchError提供派发阶段的容错钩子reset()用于清理变换内部的跨事件状态例如箭头连字的 ASCII 光标跟踪当 view 失活/销毁时由执行壳调用。2.2 生命周期五步从 beforeinput 到事务派发执行壳的完整处理链路集中在handleRichEditorBeforeInput见 richEditorInputTransform.tsfunction handleRichEditorBeforeInput( event: InputEvent, { readView, transforms }: OmitMountRichEditorInputTransformsOptions, dom | signal, ): void { const view readReadyInputView({ readView, transforms }) if (!view) return if (isComposingInput(event, view)) return runInputTransforms(event, view, transforms) }五个环节逐一拆解第一步读取并校验实时 view。readReadyInputViewL91-L101通过readView闭包拿到当前EditorView若拿不到或 view 已失效则调用resetInputTransforms重置所有变换的状态并放弃处理。第二步守卫过期 view。isLiveEditorViewL52-L58检查两层view.isDestroyed是否为真以及 view 的 DOM 节点是否已从文档中断开isConnected false。这解决了 BlockNote 编辑器在异步加载/卸载过程中beforeinput事件晚到的问题。第三步跳过 IME 组合输入。isComposingInputL60-L66从三个维度判断是否处于输入法组合阶段event.isComposing、inputType是否包含composition字样、以及view.composing状态。IME 组合中的按键不应触发 Markdown 变换否则会干扰中文、日文等输入法。第四步逐个运行变换。runInputTransformsL142-L148使用transforms.some(...)任何一个变换返回已处理true即短路停止不再运行后续变换——这保证了多个语法规则之间不存在竞争与重复改写。第五步完成变换。completeInputTransformL118-L128在读取结果后若结果为RECOVERED_INPUT_TRANSFORM_ERROR已恢复的错误或派发失败则不阻止原生输入否则派发事务且仅当preventDefault为真时才调用event.preventDefault()。2.3 错误恢复统一的遥测与回退策略变换的执行与事务派发都被try/catch包裹见 readTransformResult 与 dispatchRichEditorInputTransaction。捕获到的错误会交给recoverRichEditorInputTransformErrorL68-L76export function recoverRichEditorInputTransformError(error: unknown): boolean { if (!isRecoverableEditorTransformError(error)) return false reportRecoveredEditorTransformError( richEditorTransformRecoveryErrorReason(error) ?? transform_error, error, ) return true }只有可恢复的编辑器变换错误才会被吞掉并上报原因字符串缺省为transform_error不可恢复的错误会被重新抛出交由上层处理。判断与上报的实现来自 richEditorTransformErrorRecoveryExtension.ts它同时被编辑器图片插入editorImageInsertion.ts与 schema 构建editorSchema.tsx复用——这也是同一条恢复策略在 ADR 后果中的体现所有 Markdown 输入变换共享同一个遥测事件与回退策略。2.4 挂载方式捕获阶段的单一监听器mountRichEditorInputTransformsL161-L173在编辑器 DOM 上注册一个捕获阶段capture: true的beforeinput监听器并利用AbortSignalsignal在扩展卸载时自动移除dom.addEventListener(beforeinput, ((event: InputEvent) { handleRichEditorBeforeInput(event, { readView, transforms }) }) as EventListener, { capture: true, signal, })而createRichEditorInputTransformExtensionL175-L195则将其封装为 BlockNote 扩展通过createExtension(({ editor }) ...)拿到编辑器实例readView指向editor._tiptapEditor.viewmount阶段挂载监听器。三、组合层一条扩展四个特性共享执行壳之上是组合层 richEditorInputTransformExtension.tsexport const createRichEditorMarkdownInputTransformExtension createRichEditorInputTransformExtension({ createTransforms: () [ createArrowLigatureInputTransform(), createMarkdownHighlightInputTransform(), createMathInputTransform(), createTrackedWikilinkInputTransform(), ], key: richEditorMarkdownInputTransform, })四个特性变换被组合为一个扩展key 为richEditorMarkdownInputTransform。主编辑器与隐藏编辑器探针都使用同一个扩展主编辑器Editor.tsx 在扩展列表中挂载createRichEditorMarkdownInputTransformExtension()旁边是共享的createRichEditorTransformErrorRecoveryExtension()隐藏探针HiddenEditorMemoryProbe.tsx 同样挂载该扩展用于内存/性能探测场景这印证了 ADR 中由主编辑器与隐藏编辑器探针使用的表述。相比原先每个特性一个独立beforeinput监听器现在只有一个监听器在调度四条语法规则。四、特性文件只做匹配不做壳按照决策特性文件仅负责语法匹配与事务构造。逐个看四个实现4.1 箭头连字arrowLigaturesExtension.tsarrowLigaturesExtension.ts 维护一个跨事件状态literalAsciiCursor用于跟踪ASCII 箭头尚未完成时光标应落的位置因为-的第一字符-会先被正常输入需要记住它等键入时回填替换。关键逻辑在buildArrowLigatureTransactionL77-L114可写光标检查getWritableCursor要求选区from to折叠选区否则不处理代码块/代码上下文守卫isCodeContextL48-L58沿选区祖先链向上查找type.spec.code或codeBlock节点命中则禁用连字保持代码原样前缀采样取光标前PREFIX_CONTEXT_LENGTH 2个字符交给 utils/arrowLigatures.ts 的resolveArrowLigatureInput做精确匹配事务构造state.tr.insertText(resolution.change.insert, from, to)替换 ASCII 序列为箭头字符。其返回值带preventDefault: true阻止原生插入与ignoreDispatchError: true派发失败时仅重置literalAsciiCursor不抛错——这是在共享壳的钩子上定制容错策略的典型例子。4.2 行内数学mathInputExtension.tsmathInputExtension.ts 负责两种触发1完成型输入变换createMathInputTransformL324-L339监听插入行内空白空格/制表等与插入段落/换行insertParagraph、insertLineBreak见 L13。当光标前存在完整的$...$数学片段时replaceCompletedInlineMathL96-L112通过 utils/mathMarkdown.ts 的readCompletedInlineMathAtEnd解析 LaTeX并用state.tr.replaceWith(...)将文本替换为mathInline节点MATH_INLINE_TYPE。若触发输入是空白则在 math 节点后补插该空白并preventDefault若是换行则不阻止原生输入。2编辑已渲染数学源当光标落在 math 节点内键盘 Enter/F2见handleMathKeyDownL308-L322或双击已渲染的 math 元素handleRenderedMathDoubleClickL291-L306时将节点还原为$latex$文本源并选中其中的 LaTeX 内容以便直接编辑同时上报遥测事件math_source_edit_reopened。这里同样复用了dispatchRichEditorInputTransaction与recoverRichEditorInputTransformError见 restoreMathSource。另外注意selectionHasCodeMarkL64-L67光标带code标记时不触发数学变换避免破坏行内代码。4.3 高亮标记markdownHighlightInputExtension.tsmarkdownHighlightInputExtension.ts 监听键入最后的FINAL_MARKDOWN_HIGHLIGHT_INPUT见 L16。replaceCompletedMarkdownHighlightL48-L75流程通过 markdownHighlightInputReplacement.ts 的readMarkdownHighlightInputReplacement解析光标前文本判定...语法是否完整检查选区与替换范围内是否带 code 标记/位于代码块selectionHasCodeMark/rangeHasCodeMark/isCodeBlockTextblock实现见 markdownHighlightInputMarks.ts命中则放弃派发事务tr.delete删除开闭再用addHighlightMarks为中间内容添加 highlight 标记L68-L74。该特性与高亮渲染、快捷键、工具栏控件共享同一套模型层markdownHighlightModel.ts、markdownHighlightRange.ts、markdownHighlightShortcutExtension.ts以及 extensions/markdownHighlight.tsProseMirror 扩展定义语法由 utils/markdownHighlightMarkdown.ts 提供其中MARKDOWN_HIGHLIGHT_STYLE常量被组合层测试引用。4.4 维基链接wikilinkInputExtension.tswikilinkInputExtension.ts 监听键入]]的收尾]CLOSING_WIKILINK_INPUT见 L9。它同样具备代码块/代码标记守卫isCodeBlockTextblock、selectionHasCodeMarkL36-L50光标必须处于折叠选区且父节点是文本块命中后把[[目标]]文本收敛为wikilink节点WIKILINK_NODE_TYPE。从源码结构看它采用与高亮特性相同的光标前文本读取 → 替换区间计算 → 事务构造模式并与 InlineWikilinkInput.tsx 等组件构成完整的维基链接输入闭环。五、为什么是共享原语 特性匹配器备选方案对比ADR-0137 的 Options Considered 部分给出了三方案对比见 docs/adr/0137-shared-rich-editor-input-transforms.md方案优势代价共享变换原语 特性自有匹配器采纳消除重复的监听/派发/组合/恢复代码同时让每条语法规则局部化、可独立测试需要一次性的抽象设计投入单一巨型 Markdown 输入扩展监听器数量最少无关语法规则混在一个文件未来特性难以独立测试每个特性一个扩展保留局部所有权重复的边缘情况外壳随变换增多而发散组合层测试 richEditorInputTransformExtension.test.ts 印证了可独立测试的价值它构造一个带beforeInputListener、mock 事务addMark/delete/insertText/replaceWith/scrollIntoView与 mock view 的夹具直接驱动createRichEditorMarkdownInputTransformExtension产生的监听器验证箭头、高亮、数学、维基链接四条规则在同一执行路径下的行为。特性级测试arrowLigaturesExtension.test.ts、markdownHighlightInputExtension.test.ts、mathInputExtension.test.ts、wikilinkInputExtension.test.ts则各自聚焦单条语法的正反例。六、落地经验向共享管线接入新 Markdown 特性的检查清单结合 ADR 后果与源码实现未来在 Tolaria 中新增 Markdown 输入便利特性的标准流程可以归纳为不要新增捕获阶段beforeinput扩展而是实现一个RichEditorInputTransform对象handleBeforeInput 可选reset在handleBeforeInput中先做输入事件过滤如event.inputType insertText、event.data内容匹配不匹配立即返回null复用统一的上下文守卫折叠选区、isTextblock父节点、代码块/code标记排除、IME 组合排除这些在共享壳中已统一处理构造 ProseMirror 事务返回给执行壳由壳负责派发、preventDefault决策与错误恢复需要跨事件状态的特性如箭头连字的 ASCII 光标跟踪实现reset()让壳在 view 失活时清理将新 transform 加入 richEditorInputTransformExtension.ts 的createTransforms数组主编辑器与隐藏探针自动生效为每条规则补充特性级测试并为共享壳补充组合级测试覆盖短路停止恢复错误不阻止原生输入IME 跳过等边界。七、结语ADR-0137 是 Tolaria 编辑器架构中收敛重复、保留自治的一个典型样本共享原语负责所有输入变换共有的风险过期 view、IME、事务派发、错误恢复特性文件只回答这段语法该不该变成节点/标记这一个问题。从-连字、$...$数学、高亮到[[维基链接]]四条规则现在共享同一条beforeinput执行路径、同一个遥测事件与同一个回退策略未来的扩展点也由此被清晰地固定下来。对于任何基于 BlockNote/ProseMirror 构建富文本编辑器的项目这套模式都值得借鉴——它既避免了beforeinput扩展的碎片化又没有牺牲单条语法规则的可读性与可测试性。参考文件速查架构决策docs/adr/0137-shared-rich-editor-input-transforms.md共享执行壳src/components/richEditorInputTransform.ts变换组合层src/components/richEditorInputTransformExtension.ts、组合层测试 src/components/richEditorInputTransformExtension.test.ts特性实现arrowLigaturesExtension.ts、mathInputExtension.ts、markdownHighlightInputExtension.ts、wikilinkInputExtension.ts错误恢复richEditorTransformErrorRecoveryExtension.ts使用方Editor.tsx、HiddenEditorMemoryProbe.tsx语法工具utils/arrowLigatures.ts、utils/mathMarkdown.ts、utils/markdownHighlightMarkdown.ts【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Tolaria 富文本编辑器输入变换统一架构解析：共享 beforeinput 执行管线（ADR-0137 实践指南）
Tolaria 富文本编辑器输入变换统一架构解析共享 beforeinput 执行管线ADR-0137 实践指南【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria导读本文以 Tolaria 仓库中的架构决策记录 docs/adr/0137-shared-rich-editor-input-transforms.md 为主体深入剖析 Tolaria 富文本BlockNote/ProseMirror编辑器中 Markdown 风格输入变换的统一执行管线。你将理解箭头连字-→ 箭头符号、行内数学公式$...$、高亮标记、维基链接[[...]]等输入特性为何要收敛到一个共享的beforeinput执行路径各自的语法匹配如何保持独立以及统一后的错误恢复、IME 组合输入防护、事务派发策略在源码层面是如何落地的。读完后你将掌握这套共享执行壳 特性自有匹配器的扩展模式可直接用于自己的 BlockNote/ProseMirror 编辑器项目。一、背景多个 Markdown 便利特性如何挤进编辑器Tolaria 的富文本编辑器基于 BlockNote其底层是 ProseMirror并内置了多种 Markdown 风格的输入便利键入的 ASCII 箭头如-自动变为连字/箭头字符完成的行内数学语法自动收敛为 math 节点公式节点完成highlight语法自动收敛为持久的 highlight 标记键入]]完成维基链接语法时收敛为 wikilink 节点。这些特性最初是逐个以独立的beforeinput扩展增量添加的见 docs/adr/0137-shared-rich-editor-input-transforms.md 的 Context 部分。每个扩展都重复了同一套生命周期工作读取实时 ProseMirrorEditorView跳过 IME 组合输入composition阶段守卫过期/已销毁的 view派发dispatch事务仅在变换成功后才阻止原生输入preventDefault恢复已知的 BlockNote/ProseMirror 变换失败。语法匹配器各不相同但执行外壳高度相似。结果是每新增一个 Markdown 便利特性都面临一套略有差异的边界情况策略边缘行为容易出现分歧。二、决策一个共享的 beforeinput 执行路径ADR-0137 的决策非常明确Tolaria 将富文本编辑器的 Markdown 输入变换路由到同一条共享beforeinput执行路径。该决策在源码中的落点有三处核心文件均在 src/components 下文件职责richEditorInputTransform.ts拥有公共生命周期、事务派发与可恢复错误行为是执行壳特性文件arrowLigaturesExtension.ts / mathInputExtension.ts / markdownHighlightInputExtension.ts / wikilinkInputExtension.ts只暴露小型的 transform 对象决定当前输入事件是否应产生事务richEditorInputTransformExtension.ts组合主编辑器与隐藏编辑器探针使用的 Markdown 变换集合2.1 共享执行壳richEditorInputTransform.ts该文件定义了统一的变换契约。核心类型如下见 richEditorInputTransform.tsexport interface RichEditorInputTransformContext { view: RichEditorInputView } export interface RichEditorInputTransformResult { ignoreDispatchError?: boolean onDispatchError?: (error: unknown) void preventDefault?: boolean transaction: RichEditorInputTransaction } export interface RichEditorInputTransform { handleBeforeInput: ( event: InputEvent, context: RichEditorInputTransformContext ) RichEditorInputTransformResult | null reset?: () void }关键点返回null表示本变换不处理此输入执行壳会继续尝试下一个变换返回RichEditorInputTransformResult表示变换成功附带一个待派发的 ProseMirror 事务preventDefault控制是否阻止浏览器的原生输入只有在变换成功后才阻止避免吞掉普通输入ignoreDispatchError与onDispatchError提供派发阶段的容错钩子reset()用于清理变换内部的跨事件状态例如箭头连字的 ASCII 光标跟踪当 view 失活/销毁时由执行壳调用。2.2 生命周期五步从 beforeinput 到事务派发执行壳的完整处理链路集中在handleRichEditorBeforeInput见 richEditorInputTransform.tsfunction handleRichEditorBeforeInput( event: InputEvent, { readView, transforms }: OmitMountRichEditorInputTransformsOptions, dom | signal, ): void { const view readReadyInputView({ readView, transforms }) if (!view) return if (isComposingInput(event, view)) return runInputTransforms(event, view, transforms) }五个环节逐一拆解第一步读取并校验实时 view。readReadyInputViewL91-L101通过readView闭包拿到当前EditorView若拿不到或 view 已失效则调用resetInputTransforms重置所有变换的状态并放弃处理。第二步守卫过期 view。isLiveEditorViewL52-L58检查两层view.isDestroyed是否为真以及 view 的 DOM 节点是否已从文档中断开isConnected false。这解决了 BlockNote 编辑器在异步加载/卸载过程中beforeinput事件晚到的问题。第三步跳过 IME 组合输入。isComposingInputL60-L66从三个维度判断是否处于输入法组合阶段event.isComposing、inputType是否包含composition字样、以及view.composing状态。IME 组合中的按键不应触发 Markdown 变换否则会干扰中文、日文等输入法。第四步逐个运行变换。runInputTransformsL142-L148使用transforms.some(...)任何一个变换返回已处理true即短路停止不再运行后续变换——这保证了多个语法规则之间不存在竞争与重复改写。第五步完成变换。completeInputTransformL118-L128在读取结果后若结果为RECOVERED_INPUT_TRANSFORM_ERROR已恢复的错误或派发失败则不阻止原生输入否则派发事务且仅当preventDefault为真时才调用event.preventDefault()。2.3 错误恢复统一的遥测与回退策略变换的执行与事务派发都被try/catch包裹见 readTransformResult 与 dispatchRichEditorInputTransaction。捕获到的错误会交给recoverRichEditorInputTransformErrorL68-L76export function recoverRichEditorInputTransformError(error: unknown): boolean { if (!isRecoverableEditorTransformError(error)) return false reportRecoveredEditorTransformError( richEditorTransformRecoveryErrorReason(error) ?? transform_error, error, ) return true }只有可恢复的编辑器变换错误才会被吞掉并上报原因字符串缺省为transform_error不可恢复的错误会被重新抛出交由上层处理。判断与上报的实现来自 richEditorTransformErrorRecoveryExtension.ts它同时被编辑器图片插入editorImageInsertion.ts与 schema 构建editorSchema.tsx复用——这也是同一条恢复策略在 ADR 后果中的体现所有 Markdown 输入变换共享同一个遥测事件与回退策略。2.4 挂载方式捕获阶段的单一监听器mountRichEditorInputTransformsL161-L173在编辑器 DOM 上注册一个捕获阶段capture: true的beforeinput监听器并利用AbortSignalsignal在扩展卸载时自动移除dom.addEventListener(beforeinput, ((event: InputEvent) { handleRichEditorBeforeInput(event, { readView, transforms }) }) as EventListener, { capture: true, signal, })而createRichEditorInputTransformExtensionL175-L195则将其封装为 BlockNote 扩展通过createExtension(({ editor }) ...)拿到编辑器实例readView指向editor._tiptapEditor.viewmount阶段挂载监听器。三、组合层一条扩展四个特性共享执行壳之上是组合层 richEditorInputTransformExtension.tsexport const createRichEditorMarkdownInputTransformExtension createRichEditorInputTransformExtension({ createTransforms: () [ createArrowLigatureInputTransform(), createMarkdownHighlightInputTransform(), createMathInputTransform(), createTrackedWikilinkInputTransform(), ], key: richEditorMarkdownInputTransform, })四个特性变换被组合为一个扩展key 为richEditorMarkdownInputTransform。主编辑器与隐藏编辑器探针都使用同一个扩展主编辑器Editor.tsx 在扩展列表中挂载createRichEditorMarkdownInputTransformExtension()旁边是共享的createRichEditorTransformErrorRecoveryExtension()隐藏探针HiddenEditorMemoryProbe.tsx 同样挂载该扩展用于内存/性能探测场景这印证了 ADR 中由主编辑器与隐藏编辑器探针使用的表述。相比原先每个特性一个独立beforeinput监听器现在只有一个监听器在调度四条语法规则。四、特性文件只做匹配不做壳按照决策特性文件仅负责语法匹配与事务构造。逐个看四个实现4.1 箭头连字arrowLigaturesExtension.tsarrowLigaturesExtension.ts 维护一个跨事件状态literalAsciiCursor用于跟踪ASCII 箭头尚未完成时光标应落的位置因为-的第一字符-会先被正常输入需要记住它等键入时回填替换。关键逻辑在buildArrowLigatureTransactionL77-L114可写光标检查getWritableCursor要求选区from to折叠选区否则不处理代码块/代码上下文守卫isCodeContextL48-L58沿选区祖先链向上查找type.spec.code或codeBlock节点命中则禁用连字保持代码原样前缀采样取光标前PREFIX_CONTEXT_LENGTH 2个字符交给 utils/arrowLigatures.ts 的resolveArrowLigatureInput做精确匹配事务构造state.tr.insertText(resolution.change.insert, from, to)替换 ASCII 序列为箭头字符。其返回值带preventDefault: true阻止原生插入与ignoreDispatchError: true派发失败时仅重置literalAsciiCursor不抛错——这是在共享壳的钩子上定制容错策略的典型例子。4.2 行内数学mathInputExtension.tsmathInputExtension.ts 负责两种触发1完成型输入变换createMathInputTransformL324-L339监听插入行内空白空格/制表等与插入段落/换行insertParagraph、insertLineBreak见 L13。当光标前存在完整的$...$数学片段时replaceCompletedInlineMathL96-L112通过 utils/mathMarkdown.ts 的readCompletedInlineMathAtEnd解析 LaTeX并用state.tr.replaceWith(...)将文本替换为mathInline节点MATH_INLINE_TYPE。若触发输入是空白则在 math 节点后补插该空白并preventDefault若是换行则不阻止原生输入。2编辑已渲染数学源当光标落在 math 节点内键盘 Enter/F2见handleMathKeyDownL308-L322或双击已渲染的 math 元素handleRenderedMathDoubleClickL291-L306时将节点还原为$latex$文本源并选中其中的 LaTeX 内容以便直接编辑同时上报遥测事件math_source_edit_reopened。这里同样复用了dispatchRichEditorInputTransaction与recoverRichEditorInputTransformError见 restoreMathSource。另外注意selectionHasCodeMarkL64-L67光标带code标记时不触发数学变换避免破坏行内代码。4.3 高亮标记markdownHighlightInputExtension.tsmarkdownHighlightInputExtension.ts 监听键入最后的FINAL_MARKDOWN_HIGHLIGHT_INPUT见 L16。replaceCompletedMarkdownHighlightL48-L75流程通过 markdownHighlightInputReplacement.ts 的readMarkdownHighlightInputReplacement解析光标前文本判定...语法是否完整检查选区与替换范围内是否带 code 标记/位于代码块selectionHasCodeMark/rangeHasCodeMark/isCodeBlockTextblock实现见 markdownHighlightInputMarks.ts命中则放弃派发事务tr.delete删除开闭再用addHighlightMarks为中间内容添加 highlight 标记L68-L74。该特性与高亮渲染、快捷键、工具栏控件共享同一套模型层markdownHighlightModel.ts、markdownHighlightRange.ts、markdownHighlightShortcutExtension.ts以及 extensions/markdownHighlight.tsProseMirror 扩展定义语法由 utils/markdownHighlightMarkdown.ts 提供其中MARKDOWN_HIGHLIGHT_STYLE常量被组合层测试引用。4.4 维基链接wikilinkInputExtension.tswikilinkInputExtension.ts 监听键入]]的收尾]CLOSING_WIKILINK_INPUT见 L9。它同样具备代码块/代码标记守卫isCodeBlockTextblock、selectionHasCodeMarkL36-L50光标必须处于折叠选区且父节点是文本块命中后把[[目标]]文本收敛为wikilink节点WIKILINK_NODE_TYPE。从源码结构看它采用与高亮特性相同的光标前文本读取 → 替换区间计算 → 事务构造模式并与 InlineWikilinkInput.tsx 等组件构成完整的维基链接输入闭环。五、为什么是共享原语 特性匹配器备选方案对比ADR-0137 的 Options Considered 部分给出了三方案对比见 docs/adr/0137-shared-rich-editor-input-transforms.md方案优势代价共享变换原语 特性自有匹配器采纳消除重复的监听/派发/组合/恢复代码同时让每条语法规则局部化、可独立测试需要一次性的抽象设计投入单一巨型 Markdown 输入扩展监听器数量最少无关语法规则混在一个文件未来特性难以独立测试每个特性一个扩展保留局部所有权重复的边缘情况外壳随变换增多而发散组合层测试 richEditorInputTransformExtension.test.ts 印证了可独立测试的价值它构造一个带beforeInputListener、mock 事务addMark/delete/insertText/replaceWith/scrollIntoView与 mock view 的夹具直接驱动createRichEditorMarkdownInputTransformExtension产生的监听器验证箭头、高亮、数学、维基链接四条规则在同一执行路径下的行为。特性级测试arrowLigaturesExtension.test.ts、markdownHighlightInputExtension.test.ts、mathInputExtension.test.ts、wikilinkInputExtension.test.ts则各自聚焦单条语法的正反例。六、落地经验向共享管线接入新 Markdown 特性的检查清单结合 ADR 后果与源码实现未来在 Tolaria 中新增 Markdown 输入便利特性的标准流程可以归纳为不要新增捕获阶段beforeinput扩展而是实现一个RichEditorInputTransform对象handleBeforeInput 可选reset在handleBeforeInput中先做输入事件过滤如event.inputType insertText、event.data内容匹配不匹配立即返回null复用统一的上下文守卫折叠选区、isTextblock父节点、代码块/code标记排除、IME 组合排除这些在共享壳中已统一处理构造 ProseMirror 事务返回给执行壳由壳负责派发、preventDefault决策与错误恢复需要跨事件状态的特性如箭头连字的 ASCII 光标跟踪实现reset()让壳在 view 失活时清理将新 transform 加入 richEditorInputTransformExtension.ts 的createTransforms数组主编辑器与隐藏探针自动生效为每条规则补充特性级测试并为共享壳补充组合级测试覆盖短路停止恢复错误不阻止原生输入IME 跳过等边界。七、结语ADR-0137 是 Tolaria 编辑器架构中收敛重复、保留自治的一个典型样本共享原语负责所有输入变换共有的风险过期 view、IME、事务派发、错误恢复特性文件只回答这段语法该不该变成节点/标记这一个问题。从-连字、$...$数学、高亮到[[维基链接]]四条规则现在共享同一条beforeinput执行路径、同一个遥测事件与同一个回退策略未来的扩展点也由此被清晰地固定下来。对于任何基于 BlockNote/ProseMirror 构建富文本编辑器的项目这套模式都值得借鉴——它既避免了beforeinput扩展的碎片化又没有牺牲单条语法规则的可读性与可测试性。参考文件速查架构决策docs/adr/0137-shared-rich-editor-input-transforms.md共享执行壳src/components/richEditorInputTransform.ts变换组合层src/components/richEditorInputTransformExtension.ts、组合层测试 src/components/richEditorInputTransformExtension.test.ts特性实现arrowLigaturesExtension.ts、mathInputExtension.ts、markdownHighlightInputExtension.ts、wikilinkInputExtension.ts错误恢复richEditorTransformErrorRecoveryExtension.ts使用方Editor.tsx、HiddenEditorMemoryProbe.tsx语法工具utils/arrowLigatures.ts、utils/mathMarkdown.ts、utils/markdownHighlightMarkdown.ts【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
