Navigation API 如何统一拦截 SPA 路由：从 History API 迁移的最小方案

单页应用过去常把路由拆成三块：点击链接时调用 preventDefault()，程序跳转时调用 history.pushState()，用户点前进或后退时再监听 popstate。这些代码能工作，但它们没有共同入口，表单、脚本跳转、浏览器按钮和链接点击很容易走出不同分支。Navigation API 的价值不是换一个方法名，而是用 navigate 事件集中观察导航，再只拦截当前应用真正能处理的同源地址。

旧路由的麻烦不在 pushState 本身

History API 只负责历史记录，不会替应用统一发现所有导航。常见实现需要分别处理链接点击、代码调用和 popstate。只要某个入口漏掉鉴权、加载态或埋点，用户就会看到“地址变了但内容没变”，或者后退以后页面状态没有恢复。

function openPage(path) {
  history.pushState({}, "", path);
  renderByPath(path);
}

window.addEventListener("popstate", () => {
  renderByPath(location.pathname);
});

document.addEventListener("click", (event) => {
  const link = event.target.closest("a");
  if (!link || link.origin !== location.origin) return;
  event.preventDefault();
  openPage(link.pathname);
});

这段最小代码还没处理下载链接、修饰键点击、哈希跳转、表单数据和跨域地址。继续补条件当然可行，但导航语义会逐渐散落到多个监听器里，代码审查时很难确认每种入口是否都经过同一套路由规则。

Navigation API 把哪些责任收回到一个入口

Navigation API 通过全局 navigation 对象暴露当前浏览上下文的同源历史条目，并在导航开始时触发 navigate。处理器拿到的 NavigateEvent 包含目标地址、导航类型和是否能够拦截等信息。应用不必猜这次变化来自链接、脚本还是浏览器按钮，而是先判断“该不该接管”。

最小可用写法如下：

if ("navigation" in window) {
  navigation.addEventListener("navigate", (event) => {
    const target = new URL(event.destination.url);

    if (!event.canIntercept) return;
    if (target.origin !== location.origin) return;
    if (event.downloadRequest !== null) return;
    if (!target.pathname.startsWith("/docs/")) return;

    event.intercept({
      async handler() {
        showLoading(target.pathname);
        try {
          const page = await loadDocument(target.pathname);
          renderDocument(page);
        } catch (problem) {
          renderRouteError(target.pathname, problem);
        }
      },
    });
  });
}

intercept() 会让这次导航由应用处理。官方文档特别提醒，导航提交后 URL 可能已经改变，因此异步内容尚未返回时要显示加载状态，失败时也不能只把异常留在控制台。

四道边界检查比拦截代码更重要

先信任 canIntercept，而不是自己推测

event.canIntercept 是浏览器给出的能力判断。跨源导航等不能安全接管的场景会得到 false，此时直接返回，让浏览器执行普通导航。不要为了维持 SPA 外观去阻止本应离开站点的地址。

再限定同源与业务路径

即便可以拦截，也不表示应用理解所有 URL。示例只接管 /docs/，登录、支付、文件下载和服务端生成页仍可走完整页面导航。边界越具体，迁移风险越低。

下载与表单要单独决定

downloadRequest 非空时应优先保留浏览器下载行为。带表单数据的导航也需要业务明确支持，不能把它当成普通 GET 页面加载；如果新路由器没有提交、重复发送和错误恢复设计，就不要拦截。

哈希变化不必全部重绘

页面内目录跳转通常只需要滚动到锚点。若路由器把每次哈希变化都当成整页数据加载，不但浪费请求，还可能破坏浏览器原生滚动。可以根据事件信息和目标 URL 判断是否只保留默认行为。

地址变化、内容加载和滚动要分开理解

旧代码常把“写入历史”和“渲染成功”放在一个函数里，导致异常时难以解释当前状态。Navigation API 允许在拦截处理器里异步加载内容，还提供滚动相关控制。更稳妥的设计是先把导航请求分成应用可理解的同源页面与应交还浏览器的场景，再明确三个状态：导航已提交、主要内容已可用、次要内容仍在加载。

例如文章正文加载完毕后，可以先渲染正文并在合适时机调用事件提供的滚动能力，再继续加载相关推荐。这样用户不用等待非关键内容，也不会因为路由器过早滚动而看不到目标段落。焦点管理同样需要真实页面验收：页面切换后键盘用户应能感知新内容，而不是仍停留在已经消失的链接上。

从 History API 迁移时保留一条渐进回退

Navigation API 进入 Baseline Newly available，意味着当前主流浏览器的新版本已经具备一致支持，但“新版本可用”不等于项目的全部用户已经升级。最简单的迁移方式是保留现有 History 路由器，把 Navigation API 作为新入口：

function installRouter() {
  if ("navigation" in window) {
    installNavigationRouter();
    return;
  }

  installHistoryRouter();
}

两条入口应复用同一个 matchRoute() 和 renderRoute()，而不是维护两套页面规则。这样回退层只负责发现导航，业务匹配、数据加载和错误页仍是一份实现。等真实访问数据证明旧浏览器占比足够低，再决定是否移除 History 分支。

失败处理决定这个路由器能不能上线

异步处理器失败时，URL 可能已经指向新页面。此时静默回到旧内容会造成“地址与页面不一致”。更清楚的做法是渲染与目标路径对应的错误状态，提供重试和完整刷新按钮；如果失败来自会话失效，则跳到明确的登录入口。

上线前用这份检查单验收

• 链接点击、脚本跳转、前进和后退是否都进入同一套路由匹配。
• 跨源、下载、未知路径和不支持的表单是否会回到浏览器默认行为。
• 快速连续导航时，旧请求结果是否可能覆盖新页面。
• 加载失败后，地址、错误页、重试和刷新是否保持一致。
• 页面切换后的标题、焦点、滚动与可访问性提示是否正确。
• 不支持 Navigation API 的浏览器是否仍能使用 History 回退。

常见问题

Navigation API 会直接替代 React Router 或 Vue Router 吗？

不会。它提供浏览器级导航能力，框架路由器还要负责路由表、嵌套路由、数据加载和组件生命周期。更现实的关系是框架逐步把底层导航入口接到新 API。

为什么拦截后地址先变了，内容还没出现？

导航提交与异步内容完成不是同一时刻。处理器应立即呈现目标页面的加载状态，并在失败时渲染与目标路径一致的错误状态。

进入 Baseline 后还要做特性检测吗？

要。Baseline 反映主流浏览器新版本的共同支持，不代表项目用户设备都已更新。使用 "navigation" in window 保留渐进增强成本很低。

结语

Navigation API 最值得迁移的地方，是把多种导航来源汇总到一个可判断、可拦截的入口。真正稳妥的最小方案不是“所有跳转都拦”，而是先确认浏览器允许、目标同源、业务路由可处理，再把渲染交给应用；跨源、下载和未知路径继续由浏览器兜底。这样既减少 History API 周边的分散监听，也不会为了 SPA 外观牺牲浏览器原本可靠的导航语义。