发布时间：2026 年 4 月 20 日
Chrome 计划在今年晚些时候发布我们之前一直在实验的 Soft Navigations API。为此，我们将在 Chrome 147 至 Chrome 149 中再提供一次源试用。此试用版将之前试用版的反馈纳入了 API 的预期最终形态。我们建议对此功能感兴趣的网站所有者在发布前对 API 的预期最终形态进行最终测试。
什么是软导航？
“软导航”是指 JavaScript 拦截导航（例如，点击链接）并更新现有网页上的内容，而不是加载新网页，同时地址栏中的网址仍会更新。对于用户而言，这些操作与常规导航操作相同，但从浏览器的角度来看，网页仍然是原始网页。
对软导航 API 的需求
软导航 API 是一项提议的 API，用于检测单页应用 (SPA) 网站使用的软导航。由于软导航不会发生实际的网页导航，因此 JavaScript 必须手动管理通常在导航时发生的某些操作。借助当前的 API，可以执行某些操作，例如管理导航历史记录。不过，对于这些导航，无法执行其他操作，例如衡量核心网页指标。
Soft Navigation API 允许观察软导航。虽然启动软导航的 JavaScript（通常是 JavaScript 框架）知道何时发生导航，但网站使用的其他 JavaScript（例如，分析脚本）和浏览器本身并不知道。
Core Web Vitals 和 SPA
软导航 API 的主要驱动因素之一是允许衡量 SPA 的 Core Web Vitals。核心网页指标由浏览器（以便显示在 Chrome 用户体验报告等工具中）以及使用实时用户监控 (RUM) 解决方案的网站所有者进行衡量。
JavaScript 框架可以衡量 SPA 的 Core Web Vitals 的某些方面。尤其是 Interaction to Next Paint (INP) 和 Cumulative Layout Shift (CLS)，它们基于可在任何时间范围内进行测量的原语（分别是 Event Timing API 和 Layout Instability API）来计算这些指标。不过，其他指标（例如 Largest Contentful Paint (LCP)）仅由浏览器根据网页导航发出，并且在互动时最终确定。
该 API 如何实现对 SPA 的 Core Web Vitals 的衡量
软导航 API 引入了两个新的性能条目：
- 当所有软导航要求都得到满足时，系统会发出
SoftNavigationEntry条目。这包括导致软导航的互动的interactionId、唯一的navigationId、设置为新网址的name，以及可用于衡量软导航的首次内容绘制的各种绘制时间。 - 一个
InteractionContentfulPaint条目，用于在互动后衡量多个不断增大的内容绘制，以衡量软导航的 LCP。
您可以使用 PerformanceObserver 分别通过 soft-navigation 和 interaction-contentful-paint 类型来观察这些新条目。
该 API 还会展开每个 largest-contentful-paint、interaction-contentful-paint、event-timing 和 layout-shift 性能条目（以及其他条目），以包含一个标识符 navigationId，用于表示相应条目所针对的导航。由于 PerformanceObserver 在网页处于空闲状态之前不会观察性能条目，因此从创建性能条目的事件发生到您观察到该条目之间可能会经过一段时间。当网页非常繁忙时（例如在软导航期间），这种情况尤其明显。此 navigationId 值有助于将属性条目归因于正确的导航。
部分 interaction-contentful-paint 条目可能发生在导航之前，而另一些则发生在导航之后。soft-navigation 条目包含一个 largestInteractionContentfulPaint 条目，该条目是截至目前为止所见的最大绘制，因此您无需跟踪可能导致软导航的所有绘制。
这些功能共同支持衡量以下方面的 Core Web Vitals：
- LCP：使用
largest-contentful-paint进行初始网页加载，并使用新的interaction-contentful-paint和soft-navigation条目进行软导航。 - CLS：使用
layout-shift条目，并根据软导航的soft-navigation条目对这些条目进行切分。 - INP：使用
event条目，并根据软导航的soft-navigation条目对它们进行切分。 - FCP：使用
first-contentful-paint进行初始网页加载，并使用新soft-navigation条目中的渲染时间详细信息进行软导航。
如需了解详情，请参阅软导航文档。
软导航是如何触发的？
当发生以下情况时，软导航 API 会触发软导航：
- 发生用户互动，
- … 从而使用户看到内容绘制，
- … 并且网址更新。
该 API 采用这种方法，而不是让 JavaScript 框架“发出”软导航，或基于 Navigation API 构建，原因有以下两点：
- 首先，这包括所有现有的 SPA 网站，无需对这些网站进行任何更改。
- 其次，无论框架或开发者如何处理导航，它都能确保对软导航的构成要素有统一的理解。
即使没有用户互动或用户会认为是导航的 DOM 更新，框架或开发者也可以更新软导航的网址。它们还可以在不同时间更新网址：在互动开始时、仅在互动结束时（完成时）或在介于两者之间的任何状态。
与依赖框架和开发者选择不同，在浏览器中内置软导航检测功能可建立规范定义，从而大规模衡量软导航的 Core Web Vitals，并使这些衡量结果具有可比性。
框架和开发者还可以忽略 Soft Navigations API，并使用底层 Event Timing、Layout Instability API 和新的 InteractionContentfulPaint 性能条目来根据需要衡量其他性能指标。不过，我们建议使用用于衡量 Core Web Vitals 的 API，以便在不同网站和工具之间实现一致的衡量。
需要帮助来测试软导航 API
我们需要您的帮助来测试 Soft Navigations API，并确定它是否符合您对软导航发生时间的预期。当您认为发生了软导航时，API 是否未能报告软导航？反之，该 API 是否会过度报告您不认为是导航的导航？
自上次源试用以来发生了哪些变化
此最新迭代版本的主要变化是将 InteractionContentfulPaint 与软导航分离，以便为该性能条目实现其他使用场景，并为 SoftNavigationEntry 添加了 largestInteractionContentfulPaint 属性。
从网站的角度来看，该 API 现在还将 replaceState 纳入软导航，因为我们听取了您的反馈意见，了解到在许多情况下，这对于导航来说非常重要。我们非常希望了解 API 未识别软导航的任何其他情况。
我们还对实现进行了无数其他改进。对于那些想确切了解最新迭代中发生了哪些变化的用户，可以在软导航更改日志中找到所有更改的详细历史记录。
我们希望该 API 尽可能有用，并愿意做出进一步的更改来实现这一目标。在 API 发布之前，以及网站开始依赖于某项实现之前，对 API 进行更改会容易得多。因此，我们希望 SPA 开发者以及有兴趣衡量这些网站的网页性能的开发者测试此 API 并提供反馈。
如何测试
您可以使用 Chrome 标志或命令行选项在本地测试该 API。此外，您还可以通过源试用在实际环境中进行测试（详细了解源试用）。
如需详细了解该 API 的技术细节，尤其是如何衡量 Core Web Vitals，请参阅我们的文档或 GitHub 代码库。
此外，GitHub 和 npm 上还提供了一个实验性的 web-vitals 库软导航版本。
为了简化测试，Chrome 开发者工具的性能面板从 Chrome 145 开始会在性能轨迹中显示软导航，即使未启用该功能也是如此：
反馈
有关该 API 的反馈应作为 GitHub 上的问题提出，而有关 Chromium 实现的 bug 应在 Chrome 的问题跟踪器上报告。如果您不确定反馈属于哪个类别，也不必过于担心。我们希望您在这两个地方提供反馈，我们会在这两个地方对问题进行分流，并将其重定向到正确的位置。