Function scrollToHash

web/components/HashScroller.tsx:191–280

()

}

function scrollToHash() {
  if (typeof window === "undefined") return () => {};
  const hash = decodeHash(window.location.hash.slice(1));
  const debug = isDebug();
  if (debug) console.log("[HashScroller] scrollToHash", { hash, location: window.location.href });
  if (!hash) return () => {};

  let cancelled = false;
  const tryScroll = () => {
    if (cancelled) return;
    // 后退/前进还原阅读位置时（ScrollMemory 已接管），让位——否则会把页面又拽到
    // 锚点，盖掉用户离开时的真实滚动位置。所有滚动路径（路由变化 rAF、同页
    // hashchange）都汇到这里，故只在此判一次即可。同页脚注点击属「全新到达」、
    // ScrollMemory 不会 claim，不受影响。
    if (isScrollClaimed()) return;
    const found = document.getElementById(hash);
    if (!found) {
      if (debug) console.warn("[HashScroller] element NOT found at scroll time", hash);
      return;
    }
    // 表格锚点落在单元格上 → 归一到整张 <table>，否则会停在表格中部看不到表头
    const fresh = resolveBlockTarget(found);
    const ancestor = findScrollableAncestor(fresh);
    const elRect = fresh.getBoundingClientRect();
    if (debug) {
      const isWin = ancestor instanceof Window;
      console.log("[HashScroller] scrolling now", {
        hash,
        container: isWin ? "window" : "main",
        containerScrollTop: isWin ? window.scrollY : (ancestor as HTMLElement).scrollTop,
        containerScrollHeight: isWin
          ? document.documentElement.scrollHeight
          : (ancestor as HTMLElement).scrollHeight,
        containerClientHeight: isWin
          ? window.innerHeight
          : (ancestor as HTMLElement).clientHeight,
        elementTop: elRect.top,
        elementText: fresh.textContent?.slice(0, 50),
      });
    }
    scrollElementToTop(fresh);
    // 滚动以块起点为准（标题→标题本身），高亮则可跨多元素（标题 + 其下正文）
    flashHighlight(resolveHighlightTargets(fresh));
  };

  const onTimeout = () => {
    if (debug) {
      console.warn(
        "[HashScroller] layout 未在 ~650ms 内稳定；仍尝试滚动，但位置可能因后续异步内容（图片/dynamic import）漂移",
        { hash },
      );
    }
  };

  // Case A: 元素已在 DOM → 等 layout 稳定再滚（防止后续 mutations 让位置失效）
  const existing = document.getElementById(hash);
  if (existing) {
    whenLayoutStable(existing, tryScroll, onTimeout);