ant-design Anchor 深度解析：用 targetOffset 为每个锚点链接配置独立滚动偏移量

本文围绕 ant-design Anchor 组件的「每个链接单独设置 targetOffset」能力展开，讲解它解决什么问题、与全局 targetOffset 的优先级关系、完整的可运行示例代码，以及该功能在组件源码中的注册、滚动跳转与高亮检测三条实现链路。读完本文，你可以在页面中存在多个高度不一的固定头部（或不同分区需要不同落地位置）时，为任意锚点链接精确指定独立的滚动偏移量，并理解其在 6.4.0+ 版本中的底层工作原理。

问题背景：为什么需要"每个链接单独的滚动偏移量"

Anchor（锚点）组件用于"跳转到页面指定位置"。在典型文档型、设置型页面中，常会有一个固定在页面顶部的导航条。当用户点击锚点时，若目标元素直接滚动到视口顶端，其标题会被固定头部遮挡，因此需要设置偏移量把目标"让开"一段距离。

组件提供了全局的 targetOffset 属性来解决这个问题，但全局值只能是一个数。当页面不同区域的遮挡高度不一致——例如顶部导航 64px，而某个吸顶标签栏区域又有额外的 36px 遮挡——单一全局值就无法同时满足所有链接。于是 Anchor 在 6.4.0 版本引入了链接级 targetOffset：

通过为每个 Anchor.Link 设置 targetOffset 属性，可以为每个链接单独设置滚动偏移量。链接级别的 targetOffset 优先级高于全局的 targetOffset。

官方 API 文档中对此的表述是："设置单个锚点的滚动偏移量，会覆盖 Anchor 组件的 targetOffset 属性"，见 Anchor 组件文档 的 AnchorItem 与 Link Props 表格（均标注版本 6.4.0）。

完整示例：混合使用全局与链接级 targetOffset

官方示例 targetOffset-per-link.tsx 构造了四个 100vh 高的彩色分区和一个 20px 高的固定顶栏，其中 Part 2 与 Part 3 使用链接级 targetOffset: 50，Part 1 与 Part 4 回退到全局 targetOffset={20}。完整代码如下：

import React from 'react';
import { Anchor, Col, Row } from 'antd';

const style: React.CSSProperties = {
  height: '20px',
  backgroundColor: 'rgba(0, 0, 0, 0.85)',
  position: 'fixed',
  top: 0,
  insetInlineStart: 0,
  width: '75%',
  color: '#fff',
};

const App: React.FC = () => {
  const topRef = React.useRef<HTMLDivElement>(null);

  return (
    <Row>
      <Col span={18}>
        {/* 四个等高的锚点目标分区 */}
        <div id="part-1" style={{ height: '100vh', background: 'rgba(255,0,0,0.2)' }} />
        <div id="part-2" style={{ height: '100vh', background: 'rgba(0,255,0,0.2)' }} />
        <div id="part-3" style={{ height: '100vh', background: 'rgba(0, 0, 255, 0.2)' }} />
        <div id="part-4" style={{ height: '100vh', background: 'rgba(0, 255, 229, 0.2)' }} />
      </Col>
      <Col span={6}>
        <Anchor
          targetOffset={20}
          items={[
            { key: 'part-1', href: '#part-1', title: 'Part 1' },
            {
              key: 'part-2',
              href: '#part-2',
              title: 'Part 2 (uses link targetOffset: 50)',
              targetOffset: 50, // 链接级偏移量，覆盖全局的 20
            },
            {
              key: 'part-3',
              href: '#part-3',
              title: 'Part 3 (uses link targetOffset: 50)',
              targetOffset: 50, // 链接级偏移量，覆盖全局的 20
            },
            {
              key: 'part-4',
              href: '#part-4',
              title: 'Part 4 (uses global targetOffset: 20)',
            },
          ]}
        />
      </Col>
      <div style={style} ref={topRef}>
        <div>Fixed Top Block</div>
      </div>
    </Row>
  );
};

export default App;

要点说明：

• 该示例使用数据化的 items 配置（5.1.0 引入），其中每一项都可以携带自己的 targetOffset，这是当前推荐的写法；
• 点击 "Part 2 / Part 3" 时，目标元素会在固定顶栏下方多留 30px 余量（50 - 20）；点击 Part 1 / Part 4 时则按全局的 20px 偏移滚动；
• 若你仍在使用 JSX 子节点写法（<Anchor.Link>），targetOffset 同样可用——它定义在 AnchorLinkBaseProps 上，两种用法共享同一套实现。

相关属性一览（继承自组件 API 文档）

属性	说明	类型	默认值	版本
Anchor targetOffset	锚点滚动偏移量，默认与 offsetTop 相同	number	-
AnchorItem targetOffset	设置单个锚点的滚动偏移量，会覆盖 Anchor 组件的 targetOffset 属性	number	-	6.4.0
Link targetOffset	设置单个锚点的滚动偏移量，会覆盖 Anchor 组件的 targetOffset 属性	number	-	6.4.0

因此完整取值优先级为：链接级 targetOffset → 全局 targetOffset → 全局 offsetTop → 0，且要求组件版本 ≥ 6.4.0 才支持链接级属性。

源码剖析：三个环节如何消费链接级偏移量

下面结合 Anchor.tsx 与 AnchorLink.tsx 的实现，看链接级 targetOffset 在三个关键环节中的流动路径。

1. 链接注册阶段：把偏移量登记进"偏移表"

AnchorLink 在挂载时通过 Context 调用父组件注入的 registerLink，并把自身的 targetOffset 一并上报：

// components/anchor/AnchorLink.tsx
React.useEffect(() => {
  registerLink?.(href, targetOffset);
  return () => {
    unregisterLink?.(href);
  };
}, [href, targetOffset]);

Anchor 侧的 registerLink 将链接登记进 links 状态，并把偏移量存入一个专用 ref 表 linkTargetOffsetRef（以 href 为键）；unregisterLink 时同步清理，避免卸载的链接残留偏移记录：

// components/anchor/Anchor.tsx
const registerLink: AntAnchor['registerLink'] = (link, newTargetOffset) => {
  setLinks((prev) => {
    if (!prev.includes(link)) {
      return [...prev, link];
    }
    return prev;
  });
  // Store link-level targetOffset for scroll detection
  if (newTargetOffset !== undefined) {
    linkTargetOffsetRef.current[link] = newTargetOffset;
  }
};

2. 点击滚动阶段：链接级参数优先于全局配置

点击链接时，AnchorLink.handleClick 调用 scrollTo?.(href, targetOffset)，把链接自己的偏移量作为第一参数传给父组件的 handleScrollTo。父组件中的取值链正是"链接级 > 全局 > offsetTop > 0"的直接体现：

// components/anchor/Anchor.tsx
const finalTargetOffset = targetOffsetParams ?? targetOffset ?? offsetTop ?? 0;
y -= finalTargetOffset;
animatingRef.current = true;
scrollRequestIdRef.current = scrollTo(y, {
  getContainer: getCurrentContainer,
  callback() {
    animatingRef.current = false;
  },
});

这里 targetOffsetParams 即来自链接的参数。由于使用的是 ?? 而非 ||，即使某处显式传入 0 也能被正确识别，不会出现"传 0 反而回退全局值"的意外。

3. 滚动高亮检测阶段：判定"当前处于哪个分区"也用同一套偏移量

很多人容易忽略的一点是：targetOffset 不仅影响点击时的滚动落点，还参与滚动过程中"哪个链接应该高亮"的判定。Anchor 在每次滚动时执行 getInternalCurrentAnchor，为每个链接计算阈值：

// components/anchor/Anchor.tsx
_links.forEach((link) => {
  // ...
  const target = document.getElementById(sharpLinkMatch[1]);
  if (target) {
    // Use link-level targetOffset if provided, otherwise use global offsetTop
    const linkOffsetTop = _linkTargetOffset?.[link] ?? _offsetTop;
    const top = getOffsetTop(target, container);
    if (top <= linkOffsetTop + _bounds) {
      linkSections.push({ link, top });
    }
  }
});

其中 _linkTargetOffset 就是第 1 步登记的 linkTargetOffsetRef.current，_offsetTop 则传入全局生效值（源码中为 isNumber(targetOffset) ? targetOffset : offsetTop || 0）。也就是说：如果 Part 2 的链接级偏移是 50，那么只有当 #part-2 距离容器顶部不超过 50 + bounds 时它才会成为候选高亮项。这保证了"滚到哪儿高亮哪儿"与"点哪儿停哪儿"在几何上保持一致——两个区域各自用自己的偏移量对齐。

测试用例：行为如何被验证

Anchor.test.tsx 中有两个用例直接覆盖该特性：

• targetOffset can be set per Anchor.Link and fallback to global（约 L338）：在 targetOffset={100} 的全局锚点下，为第一个链接设置 targetOffset: 50，点击后断言滚动落点使用 50，其余链接回退使用 100；
• should use link-level targetOffset when detecting active link during scroll（约 L371）：验证滚动检测高亮时同样采用链接级偏移量而非全局值。

这两个用例分别对应上文剖析的"点击滚动"与"滚动高亮"两条链路，可作为理解该功能的可执行依据。

实战建议与适用前提

1. 动态测量头部高度。如果遮挡元素的高度不确定（例如可折叠导航），可以参考官方另一个示例 targetOffset.tsx 的做法：通过 useRef 挂载固定顶栏，在 useEffect 中读取 topRef.current?.clientHeight 写入 state，再传给 targetOffset。链接级 targetOffset 同理可以是任意运行时计算的值。
2. 与 offsetTop 的职责区分。offsetTop 控制锚点导航自身的吸顶位置和 maxHeight: calc(100vh - offsetTop) 布局，同时作为 targetOffset 缺省时的回退值；targetOffset 只控制"跳转到哪里"。二者常设为同一个头部高度以获得一致体验。
3. 版本要求。链接级 targetOffset 自 6.4.0 引入（见 index.zh-CN.md 中示例标签的 version="6.4.0" 及 API 表格），低版本项目若需要该能力需先升级；items 数据化写法则需 5.1.0+。
4. 已知限制。自 5.25.0 起锚点跳转使用 history.pushState/replaceState 实现（组件文档 FAQ 有说明），pushState 不触发页面重载，因此 :target 伪类不会自动更新；这与 targetOffset 无关，但在使用锚点做样式联动时需注意。

小结

链接级 targetOffset 是 Anchor 在 6.4.0 提供的细粒度控制：通过 AnchorLink 挂载时向父组件"登记"偏移量、点击时作为最高优先级参数参与滚动落点计算、滚动时再参与高亮判定的三段式协作，实现了"同一页面、多个链接、各停其位"。示例代码可直接复制运行，行为边界则有 __tests__/Anchor.test.tsx 中的两个专项用例兜底，是文档、源码与测试三方一致的完整能力。