鸿蒙 PC Markdown 编辑器滚动稳定性：避免双向同步递归抖动

●VON

300人浏览 · 2026-07-19 12:09:42

●VON · 2026-07-19 12:09:42 发布

在这里插入图片描述

鸿蒙 PC Markdown 编辑器滚动稳定性：避免双向同步递归抖动

双向同步滚动最大的风险不是目标位置稍有误差，而是左右两侧互相触发。源码滚动设置预览 scrollTop，预览产生 scroll事件又设置源码；两边高度和像素取整不同，反馈可能持续，表现为抖动、回弹和触控板失控。

本文基于 OhMarkdown，聚焦同步滚动的重入锁、动画帧释放、程序滚动与用户滚动竞争、模式和开关边界。代码位于 https://gitcode.com/VON-/codex_md_oh

反馈环如何产生

两个监听器：

editor.scrollDOM.addEventListener(
  'scroll',
  () => synchronizeScroll(
    editor.scrollDOM,
    preview
  ),
  { passive: true }
);

preview.addEventListener(
  'scroll',
  () => synchronizeScroll(
    preview,
    editor.scrollDOM
  ),
  { passive: true }
);

用户滚动 A，回调写 B；浏览器为 B派发事件，回调再写 A。若转换完全可逆且浏览器不派发相同值事件，可能很快停止，但不能依赖。高度比例乘除、浮点和整数像素都会产生差值。

一个布尔重入锁

let synchronizingScroll = false;

function synchronizeScroll(
  source: HTMLElement,
  target: HTMLElement
): void {
  if (!syncScrollEnabled ||
    currentMode !== 'split' ||
    synchronizingScroll) {
    return;
  }
  // 计算范围
  synchronizingScroll = true;
  target.scrollTop = targetRange *
    (source.scrollTop / sourceRange);
  window.requestAnimationFrame(() => {
    synchronizingScroll = false;
  });
}

源事件进入时锁为 false，写目标前设 true。目标产生的回调看到 true立即返回。锁不区分方向，因为同一帧只允许一侧作为源。

锁是 Web页面级状态，不通过 Bridge。scroll可能每帧多次发生，跨 ArkTS会增加延迟和乱序。

为什么不能立即释放

错误写法：

synchronizingScroll = true;
target.scrollTop = next;
synchronizingScroll = false;

scroll事件可能在赋值后的任务或渲染阶段派发，立即释放时目标回调已经看不到锁。requestAnimationFrame让锁保持到下一次绘制，覆盖同一帧的程序滚动反馈。

固定 setTimeout 100ms又太长，会吞掉用户快速转到另一侧的真实操作。动画帧约束与视觉更新节奏一致，是更小干预。

为什么监听器是 passive

{ passive: true }声明不会 preventDefault。浏览器处理滚轮和触控板时无需等待 JavaScript决定是否阻止滚动。同步只观察结果并设置另一容器，不需要取消源输入。

若未来要建立主控侧并拦截某些手势，不能随意改为非 passive；应在 wheel和 scroll职责之间分层，避免高频路径阻塞。

比例计算的边界

const sourceRange =
  source.scrollHeight - source.clientHeight;
const targetRange =
  target.scrollHeight - target.clientHeight;
if (sourceRange <= 0 || targetRange <= 0) {
  return;
}
target.scrollTop = targetRange *
  (source.scrollTop / sourceRange);

使用可滚动范围而非总高度，底部才能对应底部。任一范围为零说明短内容无可滚动位置，避免除零和 NaN。

比例结果可能为小数，浏览器内部取整或保存亚像素；反向计算不一定回原值，正是需要锁的原因。可额外夹紧0到1，但正常 scrollTop已被浏览器约束。

模式边界防止隐藏视图参与

只有 currentMode === 'split'同步。源码模式预览隐藏，预览模式编辑器隐藏；隐藏容器尺寸可能为零，参与同步没有意义。模式切换后旧 scroll事件若到达，也会被条件拒绝。

大文档保护强制 source，因此自动退出同步。同步乘法本身便宜，昂贵的是大文档预览 DOM，不能因为有同步功能而绕过保护。

用户开关优先

syncScrollEnabled=false立即返回。ArkUI Toggle通过 setSyncScroll设置：

setSyncScroll: (enabled) => {
  syncScrollEnabled = enabled;
}

关闭后两侧独立，程序不做“智能恢复”。用户可能要对照文档不同章节，开关是持续偏好而非一次命令。

重新开启时当前实现不立即对齐，要等下一次滚动。这样不会突然跳动；若产品希望即时对齐，应明确以哪侧为源。

用户快速换边的竞争

帧锁可能忽略同一帧内用户在目标侧的第一个事件。通常小于一帧不可察觉，但说明布尔锁不是完整输入仲裁。触控板惯性滚动还可能在用户开始另一侧时继续产生旧侧事件。

更强方案记录 activeSource与最近 wheel时间。wheel事件代表用户意图，程序只同步另一侧；一段静默后释放主控。也可根据鼠标所在容器选择源。引入前必须用真机证明当前锁不足，否则复杂状态机会制造新卡顿。

渲染重排与滚动

Markdown输入会重建预览 DOM，scrollHeight改变。若重排恰好发生在滚动帧，比例基于新旧高度组合可能跳动。当前 renderPreview同步执行，后续 scroll读取完成后的布局值；图片异步加载仍可能再改变高度。

在线图片被禁用，减少不确定重排。本地图片、字体和表格仍可能变化。可用 ResizeObserver在预览尺寸变化时记录并恢复比例，但恢复写入同样要使用重入锁。

程序跳转与同步的关系

点击大纲调用 CodeMirror scrollIntoView，会产生编辑器 scroll事件。在分栏且同步开启时，预览会跟随到相同比例，这是合理默认。但标题跳转若未来直接滚动两侧，就会与通用监听重复，需要标记程序来源。

搜索定位也会滚动源码并带动预览。用户可能希望预览跟随当前匹配。所有程序滚动复用相同抑制机制，不能各自写一个局部布尔导致互相不知道。

自动化验证关闭语义

测试构造120个章节，让两边都有滚动范围。把源码滚到底并派发 scroll，等待一帧后断言预览大于零。随后关闭同步，把预览设为0，断言源码位置仍大于零。

await page.evaluate(() =>
  host.OhMarkdownEditor.setSyncScroll(false)
);
await page.locator('#preview').evaluate((element) => {
  element.scrollTop = 0;
  element.dispatchEvent(new Event('scroll'));
});
expect(await page.locator('.cm-scroller')
  .evaluate((element) => element.scrollTop))
  .toBeGreaterThan(0);