HTML Academy · 课时

Navigation API：现代浏览器

Q: 「Navigation API：现代浏览器」这节课中我会学到什么？

使用 Navigation API 拦截并自定义导航 你通过在浏览器中直接运行的动手代码来练习 HTML Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

使用 Navigation API 拦截并自定义导航

Navigation API：现代浏览器 是 CoddyKit 上的免费 HTML Academy 课时。这是第 4 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 HTML Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 HTML Academy 课程共包含 4 节课。

现代替代方案

Navigation API 是 History 接口更新且功能更强大的替代方案。它将导航视为可以拦截、中止并等待完成的一等对象，更接近 SPA 在 2024 年实际处理路由的需求。

window.navigation 对象

window.navigation 提供记录项列表、当前记录项以及 navigate 事件。navigation.entries() 会返回当前历史记录中的所有记录项；navigation.currentEntry 是当前处于活动状态的记录项。与 History 接口只有一个含义不明确的 length 和无法直接读取的状态相比，它更加清晰。

navigate 事件

请监听 navigation.addEventListener("navigate", handler)，以拦截所有同文档导航，包括链接点击、表单提交、返回或前进以及程序化导航。一个统一的钩子就能替代由点击拦截、popstate 和表单提交监听器拼凑而成的方案。

navigation.addEventListener("navigate", (e) => {
  if (!e.canIntercept) return;
  e.intercept({
    handler: async () => {
      await renderPage(new URL(e.destination.url).pathname);
    }
  });
});

intercept 与处理器

调用 e.intercept({ handler }) 即可接管导航。处理器会返回一个 Promise；在它处于等待状态期间，导航处于“进行中”状态，而 URL 已经更新。这统一解决了历史上 URL 变更与视图渲染之间的竞态问题。

canIntercept 检查

并非所有导航都可以被拦截（例如跨源导航和下载）。请在调用 intercept 前检查 e.canIntercept。这一行防御性检查可以区分 SPA 导航和真正的跨源离开。

navigation.navigate 方法

navigation.navigate(url, options) 会以编程方式触发导航，效果等同于点击。返回的对象包含 committed 和 finished 两个 Promise，因此您可以等待 URL 更新完成，或等待处理器全部执行完毕。

记录项状态与标识符

每个导航记录项都有一个稳定的 key（跨重新加载保持不变）和一个 id（每个会话独有）。请使用 key 保存持久状态（例如已保存的滚动位置和表单草稿），使用 id 保存临时状态。History 接口唯一提供的状态只是一个含义不明确的数据块。

返回与前进

navigation.back() 和 navigation.forward() 是对 traverseTo 的便捷封装。它们会返回同样的一对 { committed, finished } Promise，因此您可以等待返回导航完成后再执行后续操作。

中止导航

如果用户在第一个链接仍在渲染时点击第二个链接，可以中止正在进行的导航。处理程序会通过 e.signal 接收 AbortSignal；请将其传递给获取请求，这样新导航开始时就会取消已过时的工作。

e.intercept({
  handler: async () => {
    const data = await fetch(url, { signal: e.signal });
    renderPage(await data.json());
  }
});

为什么不直接使用历史记录？

历史记录 API 虽然可用，但使用起来比较繁琐：状态变化与视图渲染相互脱节，点击处理需要手动完成，多监听器之间的协调很脆弱，滚动位置恢复也不完整。导航 API 从一开始就是为 SPA 需求设计的，解决了这些问题。

浏览器支持情况

Chrome 和 Edge 支持导航 API。Safari 和 Firefox 的支持进展较慢（截至 2026 年初）；请发布能够进行功能检测的代码（"navigation" in window），并在不可用时回退到历史记录 API + 历史状态变化事件。SvelteKit 和 TanStack 路由器等框架已经封装了这种检测。

何时采用

对于面向 Chromium 优先受众的新项目，现在就可以采用，并接受历史记录回退方案。对于面向广泛受众的公共网站，请等待 Safari 和 Firefox 支持，或使用能够抽象封装两者的路由库。这个更简单的 API 值得等待。

知识检查

与历史记录 API 中 popstate 加手动点击拦截的组合相比，导航 API 的导航事件的主要优势是什么？

总结

导航 API 通过单一的导航事件，将 SPA 导航统一起来，并提供 intercept/中止语义、稳定的每个 entry 的键以及等待异步处理程序完成的能力。它取代了历史记录 API + 历史状态事件 + 点击拦截的拼凑方案。目前 Chromium 浏览器已经支持它；在 Safari 和 Firefox 支持之前，跨浏览器代码应进行功能检测，并在需要时回退到历史记录 API。

常见问题解答

「Navigation API：现代浏览器」课时是免费的吗？

是的 — 「Navigation API：现代浏览器」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 HTML Academy 课程的其余内容，请升级到 CoddyKit PRO。 HTML Academy 课程共包含 4 节课。

「Navigation API：现代浏览器」这节课中我会学到什么？

使用 Navigation API 拦截并自定义导航你通过在浏览器中直接运行的动手代码来练习 HTML Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 HTML Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 HTML Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 4 节课，共 4 节。

「Navigation API：现代浏览器」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 HTML Academy 课中编写并运行代码吗？

能。每节 HTML Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 HTML Academy