IntelliJ Platform 中 Jewel Markdown 编辑器预览滚动同步机制深度解析ScrollingSynchronizer、映射构建与自定义渲染器适配【免费下载链接】intellij-communityIntelliJ IDEA IntelliJ Platform项目地址: https://gitcode.com/GitHub_Trending/in/intellij-community导读本文围绕 IntelliJ Platform 生态中 Jewel Markdown 的「编辑器 预览」滚动同步Scroll Synchronization功能展开核心素材来自仓库内技能文档 SCROLL-SYNC.md。Jewel Markdown 是 IntelliJ 平台组件库 Jewel 中负责 Markdown 解析与渲染的两段式渲染器按 SKILL.md 的说明其源码位于platform/jewel/markdown/本检出为部分镜像该目录未包含在内故本文以技能文档所述为准展开。阅读完本文你将掌握滚动同步的生效前提与核心类型ScrollingSynchronizer的完整 API 与当前限制、源行与渲染位置之间的映射如何由三个渲染回调构建、LocatableMarkdownBlock身份包装解决了什么隐患以及当你为编辑器预览引入自定义渲染器或自定义块时如何保住滚动同步接线而不踩坑。一、滚动同步是什么以及它何时生效滚动同步是 Jewel Markdown 的「编辑器预览」特性当用户在源编辑器如 IntelliJ 中的 Markdown 编辑面板滚动或移动光标时右侧渲染预览应跟随滚动到对应的 Markdown 块。反之如果预览滚动表现异常完全不跟随、乱跳、只滚到文档开头通常意味着下述生效前提未被满足。按文档所述滚动同步只有在以下三个条件同时成立时才工作MarkdownProcessor处于MarkdownMode.EditorPreview(scrollingSynchronizer ...)模式块渲染器是滚动同步感知的——即ScrollSyncMarkdownBlockRenderer编辑器预览样式会自动装配它源视图能够报告「当前行」预览才能据此滚动到对应位置。而在MarkdownMode.Standalone模式下处理器是无状态、一次性解析的不存在同步器也没有任何东西需要同步。因此排查「预览不跟随滚动」问题时第一件事就是确认处理器是否真的处于EditorPreview模式且同步器实例确实被传入。背景补充按 SKILL.md 的说明MarkdownMode.EditorPreview是为「用户持续打字」这类小而频繁的编辑优化的MarkdownProcessor在调用之间保留状态只重新解析发生变化的块而不是整篇文档重解析。这种有状态性决定了「编辑器预览处理器绑定单一文档、不可跨无关文档共享」的约束——这直接关联到本文第七节的 gotcha。二、核心类型ScrollingSynchronizer滚动同步的心脏是ScrollingSynchronizer文档给出的源文件位置为core/.../scrolling/ScrollingSynchronizer.kt位于 Jewel 核心模块的 scrolling 包内省略号代表 Jewel 模块内部的包前缀层级。2.1 创建ScrollingSynchronizer.create(scrollState)创建同步器的唯一入口是ScrollingSynchronizer.create(scrollState)其行为与传入的滚动状态类型强相关传入的滚动状态返回值说明ScrollState可用的PerLine同步器当前唯一受支持的路径预览按「行」粒度同步LazyListStatenull并打印一条警告日志目前不支持。这是全文最重要的一个坑详见第七节关键点create(...)可能返回null而null同步器是静默的——它不会报错只是意味着「没有同步」。调用方必须检查create(...)的返回值而不是假定它非空。2.2 传入处理器创建好的同步器要传给MarkdownMode.EditorPreview(scrollingSynchronizer)再把该markdownMode交给MarkdownProcessorval processor remember(synchronizer) { MarkdownProcessor( markdownMode MarkdownMode.EditorPreview(scrollingSynchronizer synchronizer), ) }2.3 从编辑器驱动scrollToLinesuspend fun scrollToLine(sourceLine: Int, animationSpec): UnitscrollToLine是编辑器侧驱动同步的入口它接收「源文档的第几行」并把预览滚动到与该源行最匹配的位置animationSpec控制滚动动画。内部逻辑是先在映射表中找到落在该行上的块或最接近的前驱/后继块滚动到块顶部并在适用时叠加「代码块内部的行内偏移」。2.4 重解析钩子process(action)process(action)用beforeProcessing()/afterProcessing()把一次重解析包起来在解析前后维护同步状态。好消息是当同步器存在时MarkdownProcessor.processMarkdownDocument已经会自动调用它普通使用者无需手动调用。三、映射是如何构建的三个渲染回调同步器维护一张「源行 ↔ 渲染位置」的映射表由三个渲染回调喂数据而回调的触发全部由ScrollSyncMarkdownBlockRenderer代为处理——使用标准渲染器时你不需要自己调用它们。3.1acceptBlockSpans(block, sourceRange)块到源行的映射把每个块映射到它所覆盖的源行范围。遍历是深度优先的并按「同一行上最内层块胜出」的规则去重。同时块会被包装成LocatableMarkdownBlock以区分内容完全相同、仅位置不同的块详见第四节。3.2acceptGlobalPosition(block, coordinates)块到全局 Y 坐标的映射把块映射到它在预览中的全局垂直位置。触发时机有三类首次合成first composition时发生变化的那个块位于变化块下方的所有块因为编辑会改变后续内容的布局。3.3acceptTextLayout(block, textLayout)代码块内的逐行映射记录代码块内部的「每行偏移」使滚动可以精确命中围栏代码块fenced code block或缩进代码块indented code block里的某一特定行实现源码到预览的1:1 行级映射。3.4scrollToLine的查找算法有了以上映射scrollToLine的工作方式为找到位于目标行上的块或最接近的上一/下一块滚动到块顶部若目标行落在代码块内部再叠加acceptTextLayout记录的行内偏移精确对齐到那一行。四、身份 gotcha为什么需要LocatableMarkdownBlock这是同步器设计中最容易被忽略、也最容易引发「滚动乱跳」的细节。Jewel 的许多MarkdownBlock是按内容做值相等的——两个内容完全相同的段落equals结果为真。若把原始块直接当作映射表的 key「第一个段落」的布局信息就可能覆盖「第二个段落」的滚动时会出现 A 位置内容把预览滚到 B 位置、或来回乱跳等怪异行为。解决方案同步器通过LocatableMarkdownBlock把「块 其源行范围」组合成装饰后的 key使内容相同但位置不同的块保持可区分。对实现者的要求若要编写自定义同步器必须保留这种身份纪律identity discipline——即不要让仅按内容相等的块互相覆盖映射。五、gotcha自定义渲染器必须保留滚动同步接线5.1 滚动同步不在DefaultMarkdownBlockRenderer里文档明确指出滚动同步并不在DefaultMarkdownBlockRenderer中实现而是完全由它的子类ScrollSyncMarkdownBlockRenderer源文件core/.../scrolling/ScrollSyncMarkdownBlockRenderer.kt实现。该子类通过覆写标准Render*方法做两件事把块包装进AutoScrollableBlock用于上报全局位置对代码块调用acceptTextLayout。也就是说只有ScrollSyncMarkdownBlockRenderer才会发出accept*位置回调普通的DefaultMarkdownBlockRenderer不会。IntelliJ Markdown 插件的编辑器预览直接实例化这个子类而 core/standalone/bridge 的MarkdownBlockRenderer工厂返回的不是它。由此产生两个后果后果一自定义块渲染器整体替换渲染器时。若你为编辑器预览提供了自己的MarkdownBlockRenderer——无论是继承DefaultMarkdownBlockRenderer还是从零构建——你就绕过了ScrollSyncMarkdownBlockRenderer所有块都会失去滚动同步。正确做法是改为继承ScrollSyncMarkdownBlockRenderer并在覆写中调用super或者自行复刻它的AutoScrollableBlock接线。后果二扩展提供的自定义块CustomBlock。即使ScrollSyncMarkdownBlockRenderer在起作用它也只会包装自己覆写的标准块段落 paragraph、标题 heading、围栏/缩进代码块。由MarkdownBlockRendererExtension渲染的CustomBlock不会被包装因此自定义块不报告位置预览无法滚动到它内部的某一行——此时同步器只能回退到最近的能识别位置的标准块。5.2 自定义块的 opt-in 方式AutoScrollableBlock若自定义块需要参与滚动同步可从扩展的RenderCustomBlock里显式 opt in无论上面两种情况中的哪一种只要存在ScrollingSynchronizer即可生效用AutoScrollableBlock包装块内容AutoScrollableBlock(block, synchronizer) { ... }。这是公开的实验性 API源文件位于core/.../scrolling/AutoScrollingUtil.kt它会通过onGloballyPositioned为你上报全局位置。获取同步器通过(JewelTheme.markdownMode as? MarkdownMode.EditorPreview)?.scrollingSynchronizer取得若为null说明处于 standalone 模式就正常渲染、不加包装。镜像默认渲染器的写法即可。多行自定义块需要行内定位时例如代码块场景还需在相关Text的onTextLayout回调中调用synchronizer.acceptTextLayout(block, textLayoutResult)。不加这一步块仍会作为一个整体参与滚动只是无法精确滚到块内某一行。传入的块应传RenderCustomBlock收到的那个块。默认渲染器内部用LocatableMarkdownBlock包装但AutoScrollableBlock会解包它所以直接传你的原始块即可。5.3 为什么是 opt-in 设计这是刻意的设计取舍不包装的自定义块只是「不作为滚动同步目标」对很多扩展来说完全可以接受。只有编辑器预览的 UX 确实需要「滚进你的块」时才需要加这个包装。六、接线草图完整的编辑器 预览骨架文档给出了完整接线示例这里逐行解释并补全上下文// 源编辑器暴露一个 verticalScrollState: ScrollState 以及当前光标/首可见行 val synchronizer remember(scrollState) { ScrollingSynchronizer.create(scrollState) } val processor remember(synchronizer) { MarkdownProcessor( markdownMode MarkdownMode.EditorPreview(scrollingSynchronizer synchronizer), ) } // 当编辑器滚动 / 光标移动时 LaunchedEffect(currentSourceLine, synchronizer) { synchronizer?.scrollToLine(currentSourceLine) }接线要点滚动容器预览必须基于ScrollState的滚动容器PerLine同步器依赖它。当前create(...)尚不支持LazyListState传入会得到null。因此即使大文档在其它方面更适合LazyMarkdown要获得可用的滚动同步今天也应先用ScrollState容器在承诺「支持 lazy-list 滚动同步」之前务必对照当前源码确认。样式/渲染器使用编辑器预览感知的样式/渲染器它负责装配ScrollSyncMarkdownBlockRenderer否则accept*回调根本不会发出。渲染组件对文档/长内容用LazyMarkdown渲染。空值安全synchronizer?.scrollToLine(...)用了安全调用——create可能返回null此时静默表示无同步。处理器生命周期remember(synchronizer)保证处理器与同步器同生命周期而EditorPreview是有状态的绝不能在多个无关文档之间共享同一个处理器及其同步器否则会破坏增量解析缓存、反而比Standalone更慢。七、Gotchas 速查清单将文档中的全部注意事项整理成自查清单适合排查滚动同步问题时逐项核对#注意事项后果1create(...)尚不支持LazyListState返回null无法获得滚动同步大文档场景需用ScrollState容器承载预览2null同步器 静默「无同步」必须检查create(...)返回值不要假定非空3不要在无关文档间共享EditorPreview处理器及其同步器编辑器模式有状态共享会破坏增量解析缓存、反而更慢4滚动同步依赖「滚动同步渲染器」处于激活状态普通DefaultMarkdownBlockRenderer不发出位置回调滚动不同步5编辑会打乱映射acceptGlobalPosition对「变更块及其下方块」触发acceptTextLayout不总是对变更下方的块触发不要假设每次编辑后每个块都会重新上报第 5 条需展开理解编辑后位置回调是「按需重发」的——只有受影响块变化块及其下方块会重新报告全局位置而代码块内部的文本布局回调acceptTextLayout甚至不一定对变化下方的块触发。任何依赖「编辑后全量刷新映射」的假设都不成立实现时要容忍这种增量语义。八、在 Jewel Markdown 技能体系中的位置该参考文档是仓库内jewel-markdown技能知识库的一部分SKILL.md 指向的四篇参考文档之一用于指导「构建或调试 Jewel Markdown 的解析、渲染与样式」。它与姊妹篇的分工如下SCROLL-SYNC.md本文主题编辑器预览的滚动同步及其ScrollState专属限制CODE-HIGHLIGHTING.md围栏/缩进代码块的高亮、CodeHighlighter、为什么代码默认不带样式IMAGE-LOADING.mdImageRendererExtensionImageSourceResolver、Coil3、路径解析HTML-PARSING.md内嵌 HTML、内置标签转换、MarkdownHtmlConverterExtension与对齐。在 SKILL.md 的「自定义块扩展」编写步骤中第 9 条明确要求「若该块会用于编辑器预览且应成为滚动同步目标需要 opt in滚动同步渲染器不会自动包装自定义块请在RenderCustomBlock中用AutoScrollableBlock包装你的内容——见 SCROLL-SYNC.md」。同时SKILL.md 的「自定义渲染器 Gotchas」一节把「编辑器预览滚动同步」列为自定义渲染器最容易悄悄破坏的五个行为之一其余是文本对齐、内容颜色回退、inlineContent映射、enabled状态与本文第五节的结论互相印证。九、总结Jewel Markdown 的滚动同步是一个「三层配合」机制ScrollingSynchronizer维护映射、ScrollSyncMarkdownBlockRenderer发出映射数据、MarkdownMode.EditorPreview提供有状态的增量解析环境。最典型的两个坑LazyListState尚不支持——create返回null静默无同步需改用ScrollState容器渲染器替换即丢同步——任何绕过ScrollSyncMarkdownBlockRenderer的自定义渲染器都会让所有块失去位置上报必须继承该子类并调用super或对自定义块显式使用AutoScrollableBlock与acceptTextLayoutopt in。理解三个组成部分各自的职责与触发时机排查「预览滚动不跟随」「滚动乱跳」「自定义块无法滚入」等问题时就有了清晰的路线图先验证三条件EditorPreview 模式、滚动同步渲染器在位、源视图上报行再检查同步器返回值ScrollStatevsLazyListState最后审视自定义渲染器/自定义块是否保留了AutoScrollableBlock与acceptTextLayout接线。【免费下载链接】intellij-communityIntelliJ IDEA IntelliJ Platform项目地址: https://gitcode.com/GitHub_Trending/in/intellij-community创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 IntelliJ Platform 中 Jewel Markdown 编辑器预览滚动同步机制深度解析：`ScrollingSynchronizer`、映射构建与自定义渲染器适配
IntelliJ Platform 中 Jewel Markdown 编辑器预览滚动同步机制深度解析ScrollingSynchronizer、映射构建与自定义渲染器适配【免费下载链接】intellij-communityIntelliJ IDEA IntelliJ Platform项目地址: https://gitcode.com/GitHub_Trending/in/intellij-community导读本文围绕 IntelliJ Platform 生态中 Jewel Markdown 的「编辑器 预览」滚动同步Scroll Synchronization功能展开核心素材来自仓库内技能文档 SCROLL-SYNC.md。Jewel Markdown 是 IntelliJ 平台组件库 Jewel 中负责 Markdown 解析与渲染的两段式渲染器按 SKILL.md 的说明其源码位于platform/jewel/markdown/本检出为部分镜像该目录未包含在内故本文以技能文档所述为准展开。阅读完本文你将掌握滚动同步的生效前提与核心类型ScrollingSynchronizer的完整 API 与当前限制、源行与渲染位置之间的映射如何由三个渲染回调构建、LocatableMarkdownBlock身份包装解决了什么隐患以及当你为编辑器预览引入自定义渲染器或自定义块时如何保住滚动同步接线而不踩坑。一、滚动同步是什么以及它何时生效滚动同步是 Jewel Markdown 的「编辑器预览」特性当用户在源编辑器如 IntelliJ 中的 Markdown 编辑面板滚动或移动光标时右侧渲染预览应跟随滚动到对应的 Markdown 块。反之如果预览滚动表现异常完全不跟随、乱跳、只滚到文档开头通常意味着下述生效前提未被满足。按文档所述滚动同步只有在以下三个条件同时成立时才工作MarkdownProcessor处于MarkdownMode.EditorPreview(scrollingSynchronizer ...)模式块渲染器是滚动同步感知的——即ScrollSyncMarkdownBlockRenderer编辑器预览样式会自动装配它源视图能够报告「当前行」预览才能据此滚动到对应位置。而在MarkdownMode.Standalone模式下处理器是无状态、一次性解析的不存在同步器也没有任何东西需要同步。因此排查「预览不跟随滚动」问题时第一件事就是确认处理器是否真的处于EditorPreview模式且同步器实例确实被传入。背景补充按 SKILL.md 的说明MarkdownMode.EditorPreview是为「用户持续打字」这类小而频繁的编辑优化的MarkdownProcessor在调用之间保留状态只重新解析发生变化的块而不是整篇文档重解析。这种有状态性决定了「编辑器预览处理器绑定单一文档、不可跨无关文档共享」的约束——这直接关联到本文第七节的 gotcha。二、核心类型ScrollingSynchronizer滚动同步的心脏是ScrollingSynchronizer文档给出的源文件位置为core/.../scrolling/ScrollingSynchronizer.kt位于 Jewel 核心模块的 scrolling 包内省略号代表 Jewel 模块内部的包前缀层级。2.1 创建ScrollingSynchronizer.create(scrollState)创建同步器的唯一入口是ScrollingSynchronizer.create(scrollState)其行为与传入的滚动状态类型强相关传入的滚动状态返回值说明ScrollState可用的PerLine同步器当前唯一受支持的路径预览按「行」粒度同步LazyListStatenull并打印一条警告日志目前不支持。这是全文最重要的一个坑详见第七节关键点create(...)可能返回null而null同步器是静默的——它不会报错只是意味着「没有同步」。调用方必须检查create(...)的返回值而不是假定它非空。2.2 传入处理器创建好的同步器要传给MarkdownMode.EditorPreview(scrollingSynchronizer)再把该markdownMode交给MarkdownProcessorval processor remember(synchronizer) { MarkdownProcessor( markdownMode MarkdownMode.EditorPreview(scrollingSynchronizer synchronizer), ) }2.3 从编辑器驱动scrollToLinesuspend fun scrollToLine(sourceLine: Int, animationSpec): UnitscrollToLine是编辑器侧驱动同步的入口它接收「源文档的第几行」并把预览滚动到与该源行最匹配的位置animationSpec控制滚动动画。内部逻辑是先在映射表中找到落在该行上的块或最接近的前驱/后继块滚动到块顶部并在适用时叠加「代码块内部的行内偏移」。2.4 重解析钩子process(action)process(action)用beforeProcessing()/afterProcessing()把一次重解析包起来在解析前后维护同步状态。好消息是当同步器存在时MarkdownProcessor.processMarkdownDocument已经会自动调用它普通使用者无需手动调用。三、映射是如何构建的三个渲染回调同步器维护一张「源行 ↔ 渲染位置」的映射表由三个渲染回调喂数据而回调的触发全部由ScrollSyncMarkdownBlockRenderer代为处理——使用标准渲染器时你不需要自己调用它们。3.1acceptBlockSpans(block, sourceRange)块到源行的映射把每个块映射到它所覆盖的源行范围。遍历是深度优先的并按「同一行上最内层块胜出」的规则去重。同时块会被包装成LocatableMarkdownBlock以区分内容完全相同、仅位置不同的块详见第四节。3.2acceptGlobalPosition(block, coordinates)块到全局 Y 坐标的映射把块映射到它在预览中的全局垂直位置。触发时机有三类首次合成first composition时发生变化的那个块位于变化块下方的所有块因为编辑会改变后续内容的布局。3.3acceptTextLayout(block, textLayout)代码块内的逐行映射记录代码块内部的「每行偏移」使滚动可以精确命中围栏代码块fenced code block或缩进代码块indented code block里的某一特定行实现源码到预览的1:1 行级映射。3.4scrollToLine的查找算法有了以上映射scrollToLine的工作方式为找到位于目标行上的块或最接近的上一/下一块滚动到块顶部若目标行落在代码块内部再叠加acceptTextLayout记录的行内偏移精确对齐到那一行。四、身份 gotcha为什么需要LocatableMarkdownBlock这是同步器设计中最容易被忽略、也最容易引发「滚动乱跳」的细节。Jewel 的许多MarkdownBlock是按内容做值相等的——两个内容完全相同的段落equals结果为真。若把原始块直接当作映射表的 key「第一个段落」的布局信息就可能覆盖「第二个段落」的滚动时会出现 A 位置内容把预览滚到 B 位置、或来回乱跳等怪异行为。解决方案同步器通过LocatableMarkdownBlock把「块 其源行范围」组合成装饰后的 key使内容相同但位置不同的块保持可区分。对实现者的要求若要编写自定义同步器必须保留这种身份纪律identity discipline——即不要让仅按内容相等的块互相覆盖映射。五、gotcha自定义渲染器必须保留滚动同步接线5.1 滚动同步不在DefaultMarkdownBlockRenderer里文档明确指出滚动同步并不在DefaultMarkdownBlockRenderer中实现而是完全由它的子类ScrollSyncMarkdownBlockRenderer源文件core/.../scrolling/ScrollSyncMarkdownBlockRenderer.kt实现。该子类通过覆写标准Render*方法做两件事把块包装进AutoScrollableBlock用于上报全局位置对代码块调用acceptTextLayout。也就是说只有ScrollSyncMarkdownBlockRenderer才会发出accept*位置回调普通的DefaultMarkdownBlockRenderer不会。IntelliJ Markdown 插件的编辑器预览直接实例化这个子类而 core/standalone/bridge 的MarkdownBlockRenderer工厂返回的不是它。由此产生两个后果后果一自定义块渲染器整体替换渲染器时。若你为编辑器预览提供了自己的MarkdownBlockRenderer——无论是继承DefaultMarkdownBlockRenderer还是从零构建——你就绕过了ScrollSyncMarkdownBlockRenderer所有块都会失去滚动同步。正确做法是改为继承ScrollSyncMarkdownBlockRenderer并在覆写中调用super或者自行复刻它的AutoScrollableBlock接线。后果二扩展提供的自定义块CustomBlock。即使ScrollSyncMarkdownBlockRenderer在起作用它也只会包装自己覆写的标准块段落 paragraph、标题 heading、围栏/缩进代码块。由MarkdownBlockRendererExtension渲染的CustomBlock不会被包装因此自定义块不报告位置预览无法滚动到它内部的某一行——此时同步器只能回退到最近的能识别位置的标准块。5.2 自定义块的 opt-in 方式AutoScrollableBlock若自定义块需要参与滚动同步可从扩展的RenderCustomBlock里显式 opt in无论上面两种情况中的哪一种只要存在ScrollingSynchronizer即可生效用AutoScrollableBlock包装块内容AutoScrollableBlock(block, synchronizer) { ... }。这是公开的实验性 API源文件位于core/.../scrolling/AutoScrollingUtil.kt它会通过onGloballyPositioned为你上报全局位置。获取同步器通过(JewelTheme.markdownMode as? MarkdownMode.EditorPreview)?.scrollingSynchronizer取得若为null说明处于 standalone 模式就正常渲染、不加包装。镜像默认渲染器的写法即可。多行自定义块需要行内定位时例如代码块场景还需在相关Text的onTextLayout回调中调用synchronizer.acceptTextLayout(block, textLayoutResult)。不加这一步块仍会作为一个整体参与滚动只是无法精确滚到块内某一行。传入的块应传RenderCustomBlock收到的那个块。默认渲染器内部用LocatableMarkdownBlock包装但AutoScrollableBlock会解包它所以直接传你的原始块即可。5.3 为什么是 opt-in 设计这是刻意的设计取舍不包装的自定义块只是「不作为滚动同步目标」对很多扩展来说完全可以接受。只有编辑器预览的 UX 确实需要「滚进你的块」时才需要加这个包装。六、接线草图完整的编辑器 预览骨架文档给出了完整接线示例这里逐行解释并补全上下文// 源编辑器暴露一个 verticalScrollState: ScrollState 以及当前光标/首可见行 val synchronizer remember(scrollState) { ScrollingSynchronizer.create(scrollState) } val processor remember(synchronizer) { MarkdownProcessor( markdownMode MarkdownMode.EditorPreview(scrollingSynchronizer synchronizer), ) } // 当编辑器滚动 / 光标移动时 LaunchedEffect(currentSourceLine, synchronizer) { synchronizer?.scrollToLine(currentSourceLine) }接线要点滚动容器预览必须基于ScrollState的滚动容器PerLine同步器依赖它。当前create(...)尚不支持LazyListState传入会得到null。因此即使大文档在其它方面更适合LazyMarkdown要获得可用的滚动同步今天也应先用ScrollState容器在承诺「支持 lazy-list 滚动同步」之前务必对照当前源码确认。样式/渲染器使用编辑器预览感知的样式/渲染器它负责装配ScrollSyncMarkdownBlockRenderer否则accept*回调根本不会发出。渲染组件对文档/长内容用LazyMarkdown渲染。空值安全synchronizer?.scrollToLine(...)用了安全调用——create可能返回null此时静默表示无同步。处理器生命周期remember(synchronizer)保证处理器与同步器同生命周期而EditorPreview是有状态的绝不能在多个无关文档之间共享同一个处理器及其同步器否则会破坏增量解析缓存、反而比Standalone更慢。七、Gotchas 速查清单将文档中的全部注意事项整理成自查清单适合排查滚动同步问题时逐项核对#注意事项后果1create(...)尚不支持LazyListState返回null无法获得滚动同步大文档场景需用ScrollState容器承载预览2null同步器 静默「无同步」必须检查create(...)返回值不要假定非空3不要在无关文档间共享EditorPreview处理器及其同步器编辑器模式有状态共享会破坏增量解析缓存、反而更慢4滚动同步依赖「滚动同步渲染器」处于激活状态普通DefaultMarkdownBlockRenderer不发出位置回调滚动不同步5编辑会打乱映射acceptGlobalPosition对「变更块及其下方块」触发acceptTextLayout不总是对变更下方的块触发不要假设每次编辑后每个块都会重新上报第 5 条需展开理解编辑后位置回调是「按需重发」的——只有受影响块变化块及其下方块会重新报告全局位置而代码块内部的文本布局回调acceptTextLayout甚至不一定对变化下方的块触发。任何依赖「编辑后全量刷新映射」的假设都不成立实现时要容忍这种增量语义。八、在 Jewel Markdown 技能体系中的位置该参考文档是仓库内jewel-markdown技能知识库的一部分SKILL.md 指向的四篇参考文档之一用于指导「构建或调试 Jewel Markdown 的解析、渲染与样式」。它与姊妹篇的分工如下SCROLL-SYNC.md本文主题编辑器预览的滚动同步及其ScrollState专属限制CODE-HIGHLIGHTING.md围栏/缩进代码块的高亮、CodeHighlighter、为什么代码默认不带样式IMAGE-LOADING.mdImageRendererExtensionImageSourceResolver、Coil3、路径解析HTML-PARSING.md内嵌 HTML、内置标签转换、MarkdownHtmlConverterExtension与对齐。在 SKILL.md 的「自定义块扩展」编写步骤中第 9 条明确要求「若该块会用于编辑器预览且应成为滚动同步目标需要 opt in滚动同步渲染器不会自动包装自定义块请在RenderCustomBlock中用AutoScrollableBlock包装你的内容——见 SCROLL-SYNC.md」。同时SKILL.md 的「自定义渲染器 Gotchas」一节把「编辑器预览滚动同步」列为自定义渲染器最容易悄悄破坏的五个行为之一其余是文本对齐、内容颜色回退、inlineContent映射、enabled状态与本文第五节的结论互相印证。九、总结Jewel Markdown 的滚动同步是一个「三层配合」机制ScrollingSynchronizer维护映射、ScrollSyncMarkdownBlockRenderer发出映射数据、MarkdownMode.EditorPreview提供有状态的增量解析环境。最典型的两个坑LazyListState尚不支持——create返回null静默无同步需改用ScrollState容器渲染器替换即丢同步——任何绕过ScrollSyncMarkdownBlockRenderer的自定义渲染器都会让所有块失去位置上报必须继承该子类并调用super或对自定义块显式使用AutoScrollableBlock与acceptTextLayoutopt in。理解三个组成部分各自的职责与触发时机排查「预览滚动不跟随」「滚动乱跳」「自定义块无法滚入」等问题时就有了清晰的路线图先验证三条件EditorPreview 模式、滚动同步渲染器在位、源视图上报行再检查同步器返回值ScrollStatevsLazyListState最后审视自定义渲染器/自定义块是否保留了AutoScrollableBlock与acceptTextLayout接线。【免费下载链接】intellij-communityIntelliJ IDEA IntelliJ Platform项目地址: https://gitcode.com/GitHub_Trending/in/intellij-community创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考