企业官网建设流程全解析

Ant Design Anchor 组件 replace 属性实践：用 replaceState 管理锚点跳转的浏览器历史

【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design

本篇围绕 Ant Design（antd）Anchor（锚点）组件的replace属性展开：它控制锚点点击时是用history.replaceState还是history.pushState写入浏览器历史。读完本文，你将理解官方 demo「替换历史中的 href」的完整用法、replace在Anchor与单项items两级的 API 语义、AnchorLink中历史写入与滚动跳转的完整源码链路，以及由此衍生出的:target伪类失效等注意事项。

问题背景：锚点跳转为什么会"污染"浏览器历史栈

Anchor 组件用于展示当前页面上可供跳转的锚点链接并快速在锚点之间跳转（见 组件文档 的"何时使用"）。在没有历史管理干预的情况下，用户每点击一次锚点，浏览器历史栈就压入一条记录。假设页面有 10 个锚点，用户依次点了 5 个，此时按浏览器的"后退"按钮，并不会离开当前页，而是逐个"回退"到上一个锚点——这通常不符合用户对"后退 = 回到上一页"的直觉。

antd 的解法是：锚点点击默认通过window.history.pushState写入 hash（保证 URL 可分享、刷新后仍能定位），并允许通过replace属性改为window.history.replaceState——只替换当前历史条目中的 hash，不新增历史记录。官方示例描述（替换历史中的 href）原文为：

替换浏览器历史记录中的路径，后退按钮将返回到上一页而不是上一个锚点。

Replace path in browser history, so back button returns to previous page instead of previous anchor item.

完整示例：官方 demo replace

官方示例源码见 components/anchor/demo/replace.tsx，它是一个左右两栏布局：左侧是三段各占一屏（100vh）的目标区块，右侧是带replace属性的Anchor。完整代码如下，可直接复制运行（要求 antd 5.7.0 及以上版本，因replace属性自该版本引入）：

import React from 'react'; import { Anchor, Col, Row } from 'antd'; const App: React.FC = () => ( <Row> <Col span={16}> <div id="part-1" style={{ height: '100vh', background: 'rgba(255,0,0,0.02)' }} /> <div id="part-2" style={{ height: '100vh', background: 'rgba(0,255,0,0.02)' }} /> <div id="part-3" style={{ height: '100vh', background: 'rgba(0,0,255,0.02)' }} /> </Col> <Col span={8}> <Anchor replace items={[ { key: 'part-1', href: '#part-1', title: 'Part 1', }, { key: 'part-2', href: '#part-2', title: 'Part 2', }, { key: 'part-3', href: '#part-3', title: 'Part 3', }, ]} /> </Col> </Row> ); export default App;

示例要点：

• 三个目标区块各带唯一id（part-1/part-2/part-3），高度设为100vh以便演示滚动定位效果；
• Anchor使用items数据化配置（5.1.0 引入），每项包含key、href、title；href以#开头的 hash 形式与区块id一一对应；
• 关键点只有一个：<Anchor replace />。开启后，点击任意锚点不会向历史栈新增条目，浏览器"后退"直接离开当前页。

该 demo 在文档中的注册方式为（见 index.zh-CN.md）：<code src="./demo/replace.tsx" iframe="200">替换历史中的 href</code>，其中iframe="200"表示示例在 200px 高的独立 iframe 中预览，避免与文档页自身的 hash 冲突。

API：replace 的两个配置层级

replace在 Anchor 的 API 中存在两个层级，均见 组件 API 文档：

Anchor 组件级（对全部链接生效）：

AnchorItem 单项级（对单个锚点生效，可覆盖组件级行为）：

默认值为false，即默认行为是pushState。因此replace是一个"选择性开启"的开关：多数场景保留 push 语义（用户可以用前进/后退在锚点间游走），仅当"后退必须回到上一页"成为硬性交互要求（如长文章目录、表单步骤导航）时才开启。

从 Anchor.tsx 的类型定义可以看到组件级声明replace?: boolean；在将items渲染为链接树的createNestedLink中（Anchor.tsx#L383-L390）：

const createNestedLink = (options?: AnchorLinkItemProps[]) => Array.isArray(options) ? options.map((item) => ( <AnchorLink replace={replace} {...item} key={item.key}> {anchorDirection === 'vertical' && createNestedLink(item.children)} </AnchorLink> )) : null;

注意属性展开顺序：replace={replace}先写、{...item}后展开，因此单项item.replace会覆盖组件级replace。这实现了"全局默认替换、个别链接保留 push"（或反过来）的混合策略，无需自己维护状态。嵌套的children链接同样经由该函数递归渲染，继承同一套replace语义（仅在direction为vertical时支持嵌套，水平方向不支持子级，源码中有对应的开发期 warning）。

源码剖析：AnchorLink 中历史写入的三条分支

真正的历史操作发生在 AnchorLink.tsx 的点击处理函数中，共三条分支：

const handleClick = (e: React.MouseEvent<HTMLAnchorElement, MouseEvent>) => { onClick?.(e, { title, href }); scrollTo?.(href, targetOffset); // Support clicking on an anchor does not record history. if (e.defaultPrevented) { return; } const isExternalLink = href.startsWith('http://') || href.startsWith('https://'); // Support external link if (isExternalLink) { if (replace) { e.preventDefault(); window.location.replace(href); } return; } // Handling internal anchor link e.preventDefault(); const historyMethod = replace ? 'replaceState' : 'pushState'; window.historyhistoryMethod; };

分支一：业务方preventDefault。组件先调用用户传入的onClick并执行组件内部的平滑滚动（scrollTo），随后检查e.defaultPrevented——如果业务在onClick里调用了e.preventDefault()（比如配合路由接管），则跳过一切历史写入。这是"点击锚点不记录历史"的官方支持点（见代码注释与测试用例，下文）。

分支二：外部链接。href以http://或https://开头时：开启replace则preventDefault后用window.location.replace(href)跳转（同样不产生新历史条目）；未开启则不做任何拦截，让浏览器按<a>原生行为处理。无论哪种情况都不会调用history.pushState/replaceState去改 hash，因为当前页即将导航离开。

分支三：站内锚点（hash 链接）。这是replace最核心的路径：先e.preventDefault()阻止原生 hash 跳转，然后执行

const historyMethod = replace ? 'replaceState' : 'pushState'; window.historyhistoryMethod;

即 AnchorLink.tsx#L76-L77 处的三元选择。replaceState(null, '', href)只改写当前条目的 URL（写入#part-2这类 hash），历史栈长度不变；pushState则新增一条。两种方式的共同特点是都不触发页面重载，锚点定位完全交给组件内部的 JS 滚动（下一条分支中说明）。

滚动定位与历史写入是解耦的。点击处理里的scrollTo?.(href, targetOffset)调用的是Anchor通过 Context 下发的handleScrollTo（见 Anchor.tsx#L301-L336）：它解析href的 hash 部分、document.getElementById找到目标元素、计算容器内偏移，最终调用 components/_util/scrollTo.ts 做基于requestAnimationFrame的缓动滚动（默认时长 450ms、easeInOutCubic缓动）。期间animatingRef为true会屏蔽滚动事件的活跃链接计算，避免动画过程中高亮来回抖动。也就是说，无论replace开或关，锚点视觉行为完全一致，差异只在历史栈。

测试用例：三条可验证的断言

上述源码行为在 Anchor 单元测试 中有明确覆盖，可作为"实现事实"的交叉验证：

1. hash 链接 + replace（Anchor.test.tsx#L443-L454）：渲染<Anchor replace items={[{ key, href: '#hash', title }]} />后点击链接，断言window.history.replaceState恰好以(null, '', href)被调用一次；
2. 外部链接 + replace（Anchor.test.tsx#L456-L468）：href为http://www.example.com/#hash时点击，断言pushState与replaceState都未被调用（外部跳转交给location.replace，测试环境无法真实导航）；
3. onClick中preventDefault（Anchor.test.tsx#L254-L276）：业务onClick调用e.preventDefault()后，断言window.scrollTo被调用但pushState/replaceState均未被调用——印证分支一的"不记录历史"能力。

关联注意事项

1.:target伪类在 5.25.0+ 不再自动生效。官方 FAQ（index.zh-CN.md 的 FAQ 一节）说明：出于页面性能优化，锚点跳转的实现方式从window.location.href调整为window.history.pushState/replaceState。由于pushState/replaceState不触发页面重载，浏览器不会自动更新:target伪类的匹配状态。如果样式依赖#part-2:target { ... }这类选择器，官方给出的解法是手动构造完整 URL 作为href：

href = window.location.origin + window.location.pathname + '#xxx'

需要说明：该行为与replace无关，是pushState/replaceState两种方式的共同特征，默认配置下同样存在。

2. 版本前提。replace自 5.7.0 引入（组件级与 item 级同版本）；items数据化配置自 5.1.0 引入。另外自 4.24.0 起 Anchor 已从 class 组件重写为函数组件（FC），此前获取ref并调用内部实例方法的写法会失效——本文涉及的replace用法不受影响，但仍需注意版本下限。

3. 与affix/offsetTop/targetOffset的组合。replace只影响历史栈，滚动定位仍受getContainer、offsetTop（触发高亮的窗口偏移）、targetOffset（滚动停止位置的偏移，可逐项配置）控制，两者可自由组合。示例中<Anchor replace />未设置这些参数，即使用默认值（affix: true固定模式、offsetTop: 0）。

小结：何时开启 replace

• 默认不開啟（false）：用户希望用浏览器前进/后退在锚点间逐步游走时保留 push 语义；
• 开启组件级replace：整页锚点导航都不应干扰历史栈，"后退 = 回到上一页"，如本 demo 的三栏布局；
• 单项级覆盖：由于createNestedLink中 item 属性后展开的写法，可在单个items条目上设置replace: false（或反之），实现全局替换、个别链接保留 push 的混合策略；
• 无论开关如何，业务onClick里的e.preventDefault()始终能完全接管"不写历史"的行为，且与平滑滚动（_util/scrollTo.ts）解耦，历史语义变化不会影响锚点定位效果。

参考文件清单：demo 说明、demo 源码、Anchor.tsx、AnchorLink.tsx、单元测试、工具函数 scrollTo、中英文档。

【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design