Navigation API currentEntry 怎样读取当前导航状态

如果页面需要知道“用户现在处于哪一条导航记录”，Navigation API 可以直接从 navigation.currentEntry 读取当前的 NavigationHistoryEntry。常用信息包括 url、key、id、index 和 state；其中 key 适合保存一个稳定的条目标识，后续交给 traverseTo() 定位。

真正的使用重点不是只读一次，而是把“首次读取”和“条目变化后重新读取”组合起来。下面的代码只讨论 currentEntry、key 与 currententrychange，不把它扩展成完整路由框架。

先看 currentEntry 能读到什么

currentEntry 是只读属性，返回当前浏览上下文中的导航条目。可以先把它整理成一个轻量快照，渲染面包屑、返回按钮或调试面板时都使用这份数据。

function readNavigationSnapshot() {
  // 先判断运行环境，避免不支持 Navigation API 时直接抛出异常。
  if (!("navigation" in window) || !navigation.currentEntry) {
    return null;
  }

  const entry = navigation.currentEntry;
  return {
    // URL 说明当前条目对应的地址。
    url: entry.url,
    // key 用来在同一个导航历史中定位条目。
    key: entry.key,
    // state 是该条目保存的应用状态，可能为 null。
    state: entry.getState(),
    // index 表示条目在当前导航历史中的位置。
    index: entry.index
  };
}

const snapshot = readNavigationSnapshot();
if (snapshot) {
  console.log("当前导航快照", snapshot);
}

这里的关键边界是：currentEntry 只告诉你“当前是谁”，不会自动通知界面更新。state 也应当按应用自己的数据结构读取，不要把它误当成 URL 查询参数。

保存 key，怎样回到固定的导航条目

如果返回按钮要回到页面首次进入时的条目，建议保存首次读取到的 key。不要长期保存 index 来代替它：历史记录可能发生替换，位置更适合展示，不适合作为唯一定位依据。

let homeEntryKey = null;

function rememberHomeEntry() {
  // 首次初始化时保存入口条目的 key，后续不随 currentEntry 改写。
  if (homeEntryKey === null && "navigation" in window && navigation.currentEntry) {
    homeEntryKey = navigation.currentEntry.key;
  }
}

async function goHome() {
  // 没有可用 key 时不发起无目标的遍历。
  if (!homeEntryKey) return;

  try {
    // traverseTo() 按 key 定位条目；finished 表示导航处理已经结束。
    await navigation.traverseTo(homeEntryKey).finished;
  } catch (error) {
    // 条目可能已经被替换或释放，调用方应保留当前界面并记录原因。
    console.error("无法回到入口条目", error);
  }
}

key 的作用是把“要去哪个条目”与“它当时排在第几位”分开。若条目被 replace，同一位置的条目可能复用 key，但会得到新的 id；因此业务上应把 key 当作当前历史中的定位标识，不要把它当成跨页面、跨会话的永久数据库 ID。

用 currententrychange 同步界面

返回、前进、同文档导航、替换以及 updateCurrentEntry() 改变当前条目后，都可能触发 currententrychange。监听它，再次读取 navigation.currentEntry，就能把地址栏变化和应用状态刷新放在同一处。

function renderNavigation(entry) {
  // 将当前条目的公开信息投影到界面，不把完整 state 直接拼进 HTML。
  document.querySelector("[data-current-url]").textContent = entry?.url ?? "未读取";
  document.querySelector("[data-current-key]").textContent = entry?.key ?? "无 key";
}

function syncCurrentEntry() {
  // currententrychange 触发后重新读取，而不是复用事件发生前的对象引用。
  renderNavigation(navigation.currentEntry);
}

if ("navigation" in window) {
  // 先初始化一次，因为首次加载不会依赖 navigate 事件来填充页面。
  syncCurrentEntry();
  // 当前条目提交变化后，统一刷新依赖导航状态的界面。
  navigation.addEventListener("currententrychange", syncCurrentEntry);
}

事件监听器适合做“状态同步”，不适合代替 navigate 事件拦截链接。前者关注当前条目已经变成什么，后者关注导航即将如何发生；把两者混在一个回调里，返回和替换时更容易出现重复渲染。

初始化和兼容边界怎么处理

第一，首次加载时主动调用一次同步函数；Navigation API 当前规范并不要求首次加载触发 navigate 事件。第二，先判断 window.navigation 和 currentEntry 是否存在，旧环境可以退回项目已有的 History API 方案。第三，导航方法返回的对象有 committed 与 finished 两个等待点：前者表示可见 URL 已变化，后者表示拦截处理完成。只需要更新地址相关的轻量状态时，选择正确的等待点即可。

最后要区分三个概念：currentEntry 是当前读数，key 是当前导航历史里的定位标识，currententrychange 是读数变化后的通知。用这三个概念搭出最小同步层，就能让前端页面在返回、前进和条目状态更新后保持一致。

常见问题

currentEntry 和 History API 的 state 是一回事吗？

它们可以承载相关的应用状态，但读取入口和生命周期不同。Navigation API 通过当前导航条目统一暴露 URL、key、index 和 state，迁移时不要只替换一个属性名，应同时梳理导航事件和初始化逻辑。

为什么 currententrychange 回调里还要重新读取 currentEntry？

事件表示当前条目已经发生变化，回调应以变化后的 navigation.currentEntry 为准。这样可以覆盖返回、前进、替换和状态更新，而不是依赖某一次导航操作的局部变量。