精通 Navigation API：单页应用路由与历史记录管理

Navigation API 代表了我们在单页应用 (SPA) 中处理路由和历史记录管理方式的一项重大进步。传统方法通常依赖于操作 window.location 对象或使用第三方库。尽管这些方法曾为我们提供了很好的服务，但 Navigation API 提供了一种更简化、更高效、功能更丰富的解决方案，让开发者能够对用户的导航体验进行更强的控制。

什么是 Navigation API？

Navigation API 是一种现代浏览器 API，旨在简化和增强单页应用 (SPA) 管理导航、路由和历史记录的方式。它引入了一个新的 navigation 对象，提供了一系列方法和事件，允许开发者拦截和控制导航事件、更新 URL，并在无需完全重新加载页面的情况下维护一致的浏览历史。这带来了更快、更流畅、响应更迅速的用户体验。

使用 Navigation API 的好处

• 提升性能：通过消除页面完全重新加载，Navigation API 显著提高了 SPA 的性能。不同视图之间的转换变得更快、更平滑，从而带来更具吸引力的用户体验。
• 增强控制：该 API 提供了对导航事件的精细控制，允许开发者根据需要拦截和修改导航行为。这包括阻止导航、重定向用户以及在导航发生前后执行自定义逻辑。
• 简化的历史记录管理：使用 Navigation API，管理浏览器的历史记录堆栈变得更加容易。开发者可以以编程方式添加、替换和遍历历史记录条目，确保一致且可预测的浏览体验。
• 声明式导航：Navigation API 鼓励采用更具声明性的路由方法，允许开发者以清晰简洁的方式定义导航规则和行为。这提高了代码的可读性和可维护性。
• 与现代框架集成：Navigation API 旨在与现代 JavaScript 框架和库（如 React、Angular 和 Vue.js）无缝集成。这使得开发者可以在其现有的开发工作流程中利用该 API 的功能。

核心概念与功能

1. navigation 对象

Navigation API 的核心是 navigation 对象，可通过全局 window 对象（即 window.navigation）访问。该对象提供了访问与导航相关的各种属性和方法的途径，包括：

• currentEntry: 返回一个 NavigationHistoryEntry 对象，表示导航历史记录中的当前条目。
• entries(): 返回一个由 NavigationHistoryEntry 对象组成的数组，表示导航历史记录中的所有条目。
• navigate(url, { state, info, replace }): 导航到一个新的 URL。
• back(): 导航回上一个历史记录条目。
• forward(): 导航到下一个历史记录条目。
• reload(): 重新加载当前页面。
• addEventListener(event, listener): 为导航相关事件添加事件监听器。

2. NavigationHistoryEntry

NavigationHistoryEntry 接口表示导航历史记录中的单个条目。它提供有关该条目的信息，例如其 URL、状态和唯一 ID。

• url: 历史记录条目的 URL。
• key: 历史记录条目的唯一标识符。
• id: 另一个唯一标识符，对于跟踪导航事件的生命周期特别有用。
• sameDocument: 一个布尔值，指示导航是否为同文档导航。
• getState(): 返回与历史记录条目关联的状态（在导航期间设置）。

3. 导航事件

Navigation API 会分派多个事件，允许开发者监控和控制导航行为。这些事件包括：

• navigate: 当导航被启动时分派（例如，点击链接、提交表单或调用 navigation.navigate()）。这是拦截和处理导航请求的主要事件。
• navigatesuccess: 当导航成功完成时分派。
• navigateerror: 当导航失败时分派（例如，由于网络错误或未处理的异常）。
• currentchange: 当当前历史记录条目发生变化时分派（例如，前进或后退时）。
• dispose: 当一个 NavigationHistoryEntry 不再可达时分派，例如在 replaceState 操作期间从历史记录中移除时。

使用 Navigation API 实现路由：一个实践示例

让我们通过一个简单的 SPA 示例，说明如何使用 Navigation API 实现基本路由。假设一个应用有三个视图：主页 (Home)、关于 (About) 和联系我们 (Contact)。

首先，创建一个函数来处理路由变化：

function handleRouteChange(url) {
  const contentDiv = document.getElementById('content');
  switch (url) {
    case '/':
      contentDiv.innerHTML = '
主页
欢迎来到主页！
';
      break;
    case '/about':
      contentDiv.innerHTML = '
关于
了解更多关于我们。
';
      break;
    case '/contact':
      contentDiv.innerHTML = '
联系我们
与我们取得联系。
';
      break;
    default:
      contentDiv.innerHTML = '
404 未找到
页面未找到。
';
  }
}

接下来，为 navigate 事件添加一个事件监听器：

window.navigation.addEventListener('navigate', (event) => {
  const url = new URL(event.destination.url).pathname;
  event.preventDefault(); // 阻止浏览器默认导航

  const promise = new Promise((resolve) => {
      handleRouteChange(url);
      resolve(); // 路由处理完毕后解析 Promise
  });

  event.transition = promise;
});

这段代码拦截了 navigate 事件，从 event.destination 对象中提取 URL 路径，阻止了浏览器的默认导航行为，调用 handleRouteChange 来更新内容，并设置了 event.transition promise。设置 event.transition 可以确保浏览器在视觉上更新页面之前，等待内容更新完成。

最后，你可以创建触发导航的链接：

主页 | 关于 | 联系我们

并为这些链接附加一个点击监听器：

document.addEventListener('click', (event) => {
  if (event.target.tagName === 'A' && event.target.hasAttribute('data-navigo')) {
    event.preventDefault();
    window.navigation.navigate(event.target.href);
  }
});

这样就使用 Navigation API 设置了基本的客户端路由。现在，点击这些链接将会触发一个导航事件，在不完全刷新页面的情况下更新 content div 的内容。

添加状态管理

Navigation API 还允许您将状态与每个历史记录条目关联起来。这对于在导航事件之间保留数据非常有用。让我们修改前面的示例以包含一个状态对象。

在调用 navigation.navigate() 时，你可以传递一个 state 对象：

window.navigation.navigate('/about', { state: { pageTitle: '关于我们' } });

在 navigate 事件监听器内部，你可以使用 event.destination.getState() 来访问状态：

window.navigation.addEventListener('navigate', (event) => {
  const url = new URL(event.destination.url).pathname;
  const state = event.destination.getState();
  event.preventDefault();

  const promise = new Promise((resolve) => {
      handleRouteChange(url, state);
      resolve();
  });
  event.transition = promise;

});

function handleRouteChange(url, state = {}) {
  const contentDiv = document.getElementById('content');
  let title = state.pageTitle || '我的应用'; // 默认标题

  switch (url) {
    case '/':
      contentDiv.innerHTML = '
主页
欢迎来到主页！
';
      title = '主页';
      break;
    case '/about':
      contentDiv.innerHTML = '
关于
了解更多关于我们。
';
      break;
    case '/contact':
      contentDiv.innerHTML = '
联系我们
与我们取得联系。
';
      break;
    default:
      contentDiv.innerHTML = '
404 未找到
页面未找到。
';
      title = '404 未找到';
  }
  document.title = title;
}

在这个修改后的示例中，handleRouteChange 函数现在接受一个 state 参数，并用它来更新文档标题。如果没有传递状态，标题将默认为 '我的应用'。

使用 navigation.updateCurrentEntry()

有时你可能希望更新当前历史记录条目的状态，而不触发新的导航。navigation.updateCurrentEntry() 方法允许你做到这一点。例如，如果用户在当前页面上更改了某个设置，你可以更新状态以反映该更改：

function updateUserSetting(setting, value) {
  const currentState = navigation.currentEntry.getState() || {};
  const newState = { ...currentState, [setting]: value };
  navigation.updateCurrentEntry({ state: newState });
  console.log('已将设置:', setting, '更新为', value);
}

// 用法示例：
updateUserSetting('theme', 'dark');

此函数检索当前状态，合并更新后的设置，然后用新状态更新当前历史记录条目。

高级用例与注意事项

1. 处理表单提交

Navigation API 可用于处理 SPA 中的表单提交，防止页面完全重新加载并提供更无缝的用户体验。您可以拦截表单提交事件，并使用 navigation.navigate() 来更新 URL 并显示结果，而无需完全重新加载页面。

2. 异步操作

在处理导航事件时，您可能需要执行异步操作，例如从 API 获取数据。event.transition 属性允许您将一个 promise 与导航事件关联起来，确保浏览器在更新页面之前等待异步操作完成。具体用法请参见上面的示例。

3. 滚动位置恢复

在导航期间保持滚动位置对于提供良好的用户体验至关重要。Navigation API 提供了在历史记录中后退或前进时恢复滚动位置的机制。您可以使用 NavigationHistoryEntry 的 scroll 属性来存储和恢复滚动位置。

4. 错误处理

处理导航期间可能发生的错误（例如网络错误或未处理的异常）至关重要。navigateerror 事件允许您优雅地捕获和处理这些错误，从而防止应用程序崩溃或向用户显示错误消息。

5. 渐进式增强

在使用 Navigation API 构建 SPA 时，考虑渐进式增强非常重要。请确保即使浏览器不支持 Navigation API，您的应用程序也能正常工作。您可以使用功能检测来检查 navigation 对象是否存在，并在必要时回退到传统的路由方法。

与传统路由方法的比较

SPA 中的传统路由方法通常依赖于操作 window.location 对象或使用像 react-router 或 vue-router 这样的第三方库。虽然这些方法被广泛使用且行之有效，但它们也存在一些局限性：

• 完全页面重新加载：直接操作 window.location 可能会触发页面完全重新加载，这可能会很慢并干扰用户体验。
• 复杂性：使用传统方法管理历史记录和状态可能很复杂且容易出错，尤其是在大型复杂应用中。
• 性能开销：第三方路由库可能会增加显著的性能开销，特别是如果它们没有针对您应用的特定需求进行优化。

Navigation API 通过提供一种更简化、更高效、功能更丰富的路由和历史记录管理解决方案来解决这些局限性。它消除了页面完全重新加载，简化了历史记录管理，并提供了对导航事件的精细控制。

浏览器兼容性

截至 2024 年末，Navigation API 在包括 Chrome、Firefox、Safari 和 Edge 在内的现代浏览器中得到了良好支持。然而，在您的生产应用中实施 Navigation API 之前，最好还是在 Can I use 等资源上查看最新的浏览器兼容性信息。如果必须支持旧版浏览器，请考虑使用 polyfill 或回退机制。

结论

Navigation API 是一个强大的工具，用于构建具有高级路由和历史记录管理功能的现代化、高性能 SPA。通过利用该 API 的功能，开发者可以创造更快、更流畅、更具吸引力的用户体验。虽然与使用更简单、更旧的方法相比，最初的学习曲线可能有点陡峭，但 Navigation API 的优势（尤其是在复杂应用中）使其成为一项值得的投入。拥抱 Navigation API，释放您 SPA 的全部潜力。

进一步学习

• MDN Web Docs：Navigation API
• WICG Navigation API 规范