Navigation API precommitHandler 怎么理解：导航提交前检查与回退边界

做单页应用路由管控的前端开发者，经常会碰到原生跳转拦截不彻底、自定义导航逻辑和浏览器原生回退冲突的问题，Navigation API 里的 precommitHandler 就是专门用来补全这部分能力的钩子，它运行在导航动作正式提交给页面执行之前，我们可以在这里统一做合规性检查，直接否决不符合预期的跳转，也能提前处理返回栈相关的边界场景。

precommitHandler 是 Navigation API 提供的同步回调钩子，在导航动作即将提交、页面还没开始执行实际跳转逻辑的节点触发，适合做轻量的同步校验，直接返回 false 就能取消本次导航，同时不会触发页面卸载相关的生命周期，能帮你规避大量原生导航和自定义路由逻辑冲突的问题。

在 SPA 里，权限检查经常发生在“用户已经点了链接，但新地址还没有真正提交”的瞬间。Navigation API 的 precommitHandler 就是为这个窗口准备的：它可以在 currentEntry 更新前完成检查、重定向或拒绝。简单记忆是：要阻止或改写目的地，用 precommitHandler；要在地址已经切换后加载页面，用 handler。

一、先分清 precommitHandler 和 handler

event.intercept() 可以同时接收两个回调。precommitHandler(controller) 在当前条目更新前执行，适合检查登录态、确认未保存表单，或者调用 controller.redirect() 改到真正允许的地址。它结束后浏览器才决定提交。

handler() 则属于提交后的工作：此时新 URL 已经显示，navigation.currentEntry 也已经指向新条目，适合拉取数据、替换页面内容和安排焦点。把权限判断放进 handler，用户可能先看到受限 URL，回退体验也更绕。

二、用 precommitHandler 做一次可回退的导航检查

下面的例子只处理同源、可拦截的受限路径。未登录时不先取消再手动发起第二次导航，而是让控制器直接重定向；这样中间的受限地址不会作为用户可见的业务状态停留。

navigation.addEventListener("navigate", (event) => {
  if (!event.canIntercept || !event.cancelable) return;

  const target = new URL(event.destination.url);
  if (!target.pathname.startsWith("/workspace/")) return;

  event.intercept({
    async precommitHandler(controller) {
      if (!isSignedIn()) {
        controller.redirect("/signin?next=" + encodeURIComponent(target.pathname), {
          history: "push",
          state: { reason: "auth-required" }
        });
        controller.addHandler(() => {
          showNotice("登录后才能打开工作区");
        });
      }
    },
    async handler() {
      renderWorkspace(await fetchWorkspace(target.pathname));
    }
  });
});

这里的关键不是把所有路由逻辑塞进事件监听器，而是把“提交前能否继续”和“提交后如何渲染”拆开。addHandler() 只在发生这次重定向时追加提示，避免普通工作区导航也显示登录消息。

三、把失败、提交和完成拆成三种结果

如果 precommitHandler 抛错或返回 rejected Promise，本次导航不会提交，navigateerror 会发出，调用 navigation.navigate() 得到的 committed 与 finished 也会失败。这个阶段适合保留原页面，不要提前清空内容。

如果提交前处理成功，committed 先完成：地址已更新并创建新的历史条目。随后才运行 handler；等它也成功，finished 完成并触发 navigatesuccess。因此，地址栏变化不是“数据已经加载完成”的信号。

四、上线前处理取消、兼容和降级

第一，先过滤下载、跨域和不允许拦截的导航；canIntercept 为 false 时不要调用 intercept()。第二，precommitHandler 依赖可取消事件，在非可取消事件上调用会抛出 SecurityError。第三，首次加载不会触发 navigate，SSR 或显式初始化仍然需要保留。

Navigation API 在最新浏览器中的可用性正在改善，但项目仍应做能力探测：支持时使用提交前检查，不支持时交给现有路由器或普通链接。不要同时让两套系统都接管同一次导航，否则容易出现重复请求、重复历史记录和两次提示。

const supportsNavigation = "navigation" in window;

if (supportsNavigation) {
  installNavigationGuards();
} else {
  installLegacyRouteFallback();
}

相关问题

precommitHandler 能不能代替所有权限校验？

不能。它只控制浏览器导航流程，服务端仍必须校验身份和资源权限；前端检查只是改善体验。

为什么 committed 成功但页面仍是旧内容？

因为 committed 只代表导航已提交，页面数据通常还在 handler 中异步加载，应监听 finished 或在 handler 内维护加载状态。