Navigation API:面向现代 SPA 的客户端路由原语
Navigation API:面向现代 SPA 的客户端路由原语
背景与动机
单页应用(SPA)十余年来一直依赖 History API 来模拟多页导航而无需整页刷新。然而 History API 并非为现代 SPA 的需求而设计。开发者不得不拼凑一套脆弱的方案:
- 全局监听
<a>点击,调用preventDefault(),手动执行history.pushState(),再更新 DOM。 - 单独监听
popstate以处理浏览器前进/后退。 - 漏掉某些导航类型(例如程序式
location.href更改、部分表单提交)。 - 无法读取完整历史栈或编辑非当前条目。
popstate行为不一致——在pushState/replaceState时不会触发。
这导致脆弱的路由器充满边界情况:用户可能跳转到错误视图,或丢失滚动位置。
Navigation API 解决了这些架构缺口。它提供一个集中的 navigate 事件,捕获所有导航触发源——链接点击、前进/后退、表单提交、程序式调用——并附带强大原语:intercept()、commit/finished 双阶段提交、手动滚动控制、状态管理。截至 2026 年初,随着 Safari 与 Firefox 加入 Chrome 阵营,Navigation API 已在所有主流浏览器中标记为 Baseline Newly available。
前置条件
采用 Navigation API 前,需验证支持度并准备降级方案。
浏览器支持矩阵
- Chrome / Edge: 102+
- Samsung Internet: 19.0+
- Safari: 26.2+(2025 年起)
- Firefox: 147+(2026 年起)
- iOS Safari: 26.2+
旧版浏览器完全不支持该 API。务必进行特性探测并提供传统路径。
特性探测
const hasNavigationAPI = 'navigation' in window && typeof window.navigation === 'object';若不支持,回退到基于 History API 的路由或最简 SPA shim。
if (!hasNavigationAPI) {
// 传统 History API 回退
window.addEventListener('popstate', handlePopState);
document.querySelectorAll('a[href]').forEach(link => {
link.addEventListener('click', (e) => {
if (isSameOrigin(link.href)) {
e.preventDefault();
const url = new URL(link.href);
window.history.pushState({ path: url.pathname }, '', url.pathname);
renderApp(url.pathname);
}
});
});
}构建工具配置
无需特殊打包器设置。若使用 TypeScript,确保 tsconfig.json 的 lib 包含 "DOM",最好包含带有 Navigation API 类型的较新版本。
步骤一:准备工作
第一步是用单个监听器集中导航逻辑。
基础设置
在主入口文件(如 src/router.ts)中:
if (hasNavigationAPI) {
window.navigation.addEventListener('navigate', (event) => {
// 在这里处理所有导航
});
}拦截资格检查
并非所有导航都能或都应该被拦截。检查 event.canIntercept:
- 跨源导航:
canIntercept为false,浏览器以整页刷新处理。 - 同源、同文档:可拦截。
同时跳过 event.hashChange(片段滚动)和 event.downloadRequest(文件下载)。
navigation.addEventListener('navigate', (event) => {
if (!event.canIntercept) return;
if (event.hashChange || event.downloadRequest !== null) {
return; // 让浏览器原生处理这些情况
}
const url = new URL(event.destination.url);
// 继续拦截
});关键洞察:将所有合格导航集中到一处处理,消除了多事件监听器与边界情况胶合代码的需要。
步骤二:核心实现
现在实现路由器的核心:带异步内容加载的 intercept 处理器、正确的滚动管理、状态持久化。
带异步处理器的 Intercept
intercept() 方法接收一个带有 handler 回调的对象。该回调可以是异步的。Navigation API 会等待返回的 Promise 完成后才触发 navigatesuccess。
navigation.addEventListener('navigate', (event) => {
if (!event.canIntercept) return;
if (event.hashChange || event.downloadRequest !== null) return;
const url = new URL(event.destination.url);
event.intercept({
async handler() {
// 立即显示加载状态(可选)
renderPlaceholder();
// 获取新内容(从网络或缓存)
const content = await fetchPageContent(url.pathname);
// 更新 DOM
document.getElementById('app').innerHTML = content;
}
});
});两阶段提交(高级)规范定义了 precommitHandler,用于在 URL 更新前进行重定向。若应用需要在登录流程或 A/B 测试中重写 URL,可使用它:
event.intercept({
precommitHandler: (controller) => {
if (needsAuth) {
return controller.redirect('/signin');
}
},
async handler() {
// 正常渲染
}
});手动滚动控制
默认情况下,浏览器在 intercept() 被调用时即尝试滚动恢复。对于异步渲染内容的 SPA,这往往导致在页面高度尚未确定时就滚动,结果落在错误位置或停留在顶部。
设置 scroll: 'manual',在内容就绪后调用 event.scroll():
navigation.addEventListener('navigate', (event) => {
if (!event.canIntercept) return;
event.intercept({
scroll: 'manual',
async handler() {
const data = await fetchListData();
renderList(data);
// 现在文档具有正确高度;恢复滚动位置
event.scroll();
}
});
});此模式对前进/后退导航至关重要——用户期望回到之前的滚动偏移量。
状态管理
Navigation API 允许在每个历史条目上存储任意状态。这优于 History API(状态只能在 pushState 时设置)。
导航时设置状态:
navigation.navigate('/dashboard', { state: { visitCount: 5, filters: { status: 'open' } } });检索状态:
const entry = navigation.currentEntry;
const state = entry.getState(); // { visitCount: 5, filters: { status: 'open' } }
对于非导航相关的状态变更(例如展开 <details> 元素),使用 updateCurrentEntry():
details.addEventListener('toggle', () => {
const expanded = details.open;
navigation.updateCurrentEntry({
state: { ...navigation.currentEntry.getState(), detailsExpanded: expanded }
});
});这确保浏览器前进/后退能恢复 UI 状态而无需重新加载。
与 View Transitions 集成
Navigation API 与 View Transitions API 设计为协同工作。将 DOM 更新包裹在 document.startViewTransition() 中:
navigation.addEventListener('navigate', (event) => {
if (!event.canIntercept) return;
const url = new URL(event.destination.url);
event.intercept({
async handler() {
const content = await fetchPageContent(url.pathname);
document.startViewTransition(() => {
document.getElementById('app').innerHTML = content;
});
}
});
});浏览器会拍摄旧 UI 快照、执行你的回调、再动画过渡到新状态——无需自定义动画即可获得类原生应用的过渡效果。
表单提交处理
navigate 事件为同源 POST 提交暴露 event.formData。拦截以避免页面刷新:
navigation.addEventListener('navigate', (event) => {
if (event.formData && event.canIntercept) {
event.intercept({
async handler() {
const data = event.formData;
const username = data.get('username');
await api.login(username, data.get('password'));
renderSuccess(`欢迎,${username}!`);
}
});
}
});标准 HTML 表单即可正常工作——无需 onsubmit 处理器。
导航生命周期事件
跟踪导航完成与错误:
navigation.onnavigatesuccess:handler()解决后触发。navigation.onnavigateerror:handler()拒绝时触发。navigation.transition.finished:当前导航完成的 Promise。
navigation.addEventListener('navigatesuccess', () => {
console.log('导航成功提交');
});
navigation.addEventListener('navigateerror', (event) => {
console.error('导航失败:', event.error);
// 显示回退 UI 或重试
});历史遍历
使用类型化方法进行精确控制:
navigation.back()、navigation.forward():标准遍历。navigation.traverseTo(key):通过NavigationHistoryEntry.key跳转到特定条目。navigation.reload():重新加载当前条目。
// 记住用户首次着陆的页面
const homeKey = navigation.currentEntry.key;
// 始终返回会话根节点
document.getElementById('home-btn').onclick = () => {
navigation.traverseTo(homeKey);
};步骤三:验证与调优
特性探测检查清单
在 CI 或自动化测试中断言:
test('has Navigation API support', () => {
expect('navigation' in window).toBe(true);
expect(typeof window.navigation.addEventListener).toBe('function');
});手动 QA 清单
- 点击同源链接 → URL 更新,无刷新,UI 渲染。
- 按浏览器后退 → URL 回退,滚动位置恢复(若正确使用
scroll: 'manual')。 - 提交 POST 表单 → 无刷新,渲染服务器响应。
- 程序式调用
navigation.navigate()→ 中央处理器被调用。 - 跨源链接点击 → 按预期整页刷新。
DevTools 调试
Chrome DevTools 在 Application > Navigation 面板(实验性)中显示导航拦截。在 handler() 回调内设置断点,单步调试异步 fetch 与渲染。
优雅降级策略
对于不支持的浏览器:
- 提供完整 SSR 回退(每个路由都是服务端渲染页面;链接是常规
<a>标签)。 - 最小化 polyfill:使用 History API 进行 push/pop 路由。
- 注意:Navigation API 没有真正的 polyfill。设计应用时应以 History API 为底线。
已知限制
- 首次加载:初始页面加载时不会触发
navigate。SSR 应用自然处理此问题;CSR 应用必须在启动时调用init()。 - 单作用域:API 仅在一个浏览上下文中运行。
<iframe>内的导航不可见。 - 无法重排历史:你不能移除或重新排列条目。不应持久化在历史中的临时模态框需要谨慎的状态设计。
性能考量
- 拦截期间 fetch:在提交 URL 前加载内容,若 fetch 失败可能增加感知延迟。考虑乐观 UI 更新并在错误时回滚。
- 避免嵌套 intercept:除非你谨慎处理
finishedPromise 以避免循环,否则不要在handler()内调用navigation.navigate()。 - 内存:历史条目会累积。使用
entry.dispose事件清理与已处置条目绑定的缓存:
entry.addEventListener('dispose', () => {
cache.delete(entry.key);
});最佳实践小结
- 单一事实来源:在一个
navigate监听器中处理所有导航。不要与手动pushState调用混用。 - 使用
scroll: 'manual':始终将滚动恢复推迟到异步渲染完成后。 - 利用状态:在历史条目上存储视图状态(过滤器、展开区段),以实现正确的前进/后退行为。
- 检查
canIntercept:尊重跨源与下载导航——不要强制拦截。 - 集成 View Transitions:将 DOM 更新包裹在
document.startViewTransition()中,实现流畅的内置动画。 - 为传统浏览器规划:为不支持的浏览器提供 History API 回退或 SSR 基线。
参考资料
- MDN Web Docs, Navigation API
- web.dev, Navigation API - a better way to navigate, is now Baseline Newly Available
- WICG, Navigation API Explainer
- Can I use, Navigation API support table
- MDN, NavigateEvent.intercept()
- MDN, View Transitions API