Electron NavigationEntry 对象详解：导航历史快照、PageState 与跨窗口历史恢复

2026-09-06 14:02:21作者：殷蕙予

在 Electron 中，NavigationEntry 对象是 NavigationHistory 体系的基本单元，代表某个 webContents 访问过的单个页面。它是主进程中导航历史管理能力的载体：通过 navigationHistory.getAllEntries() 可以把整段浏览历史（URL、标题、滚动位置、表单值）序列化为可持久化的纯 JSON 数据，再用 navigationHistory.restore() 将其注入另一个（尚未加载任何页面的）webContents，从而在新窗口中完整克隆甚至"回放"旧窗口的浏览历史，包括表单字段和滚动位置的还原。掌握这一结构，你就能实现窗口状态持久化、会话恢复、多窗口历史克隆等高级桌面应用功能。

NavigationEntry 对象的三个字段

根据官方结构定义（navigation-entry.md），每个 NavigationEntry 对象包含以下属性：

属性	类型	说明
`url`	`string`	该导航条目对应的页面 URL
`title`	`string`	该页面当前显示的标题
`pageState`	`string`（可选）	一个 base64 编码的数据字符串，内含 Chromium 页面状态（Page State），其中包括当前滚动位置、表单字段值等信息。它由 Chromium 在导航事件提交前以及按固定时间间隔周期性写入

三个字段的分工值得展开说明：

url 和 title 是历史栈的"身份标识"。title 对应 Chromium 内部的 GetTitleForDisplay()，会随页面标题更新而变化——C++ 侧通过 TitleWasSet(content::NavigationEntry*) 观察者回调把 Blink 发出的标题更新同步回条目对象（见 electron_api_web_contents.h 中的 TitleWasSet 声明）。
pageState 是"页面状态快照"。它不是由 Electron 自己构造的，而是直接来自 Chromium 的 blink::PageState：包含滚动坐标、DOM 表单控件的值等 UI 状态。正因为它是 base64 字符串，NavigationEntry 才能被 JSON.stringify 无损序列化到磁盘、再反序列化后跨进程/跨窗口传递——这是"会话恢复"功能成立的根本原因。

从源码结构看，pageState 的写入时机在测试用例中有明确验证：它在页面收到 unload 事件时提交，同时 Chromium 会周期性序列化页面状态（见 api-web-contents-spec.ts 中的注释）。因此如果你修改了表单值后立刻读取历史，可能拿到的是上一次周期性提交的数据；触发一次新的导航可以确保状态落盘。

NavigationHistory：NavigationEntry 的有序容器

NavigationEntry 不直接暴露为独立 API，而是由主进程中的 NavigationHistory 类管理。该类不由 'electron' 模块导出，只能通过 webContents.navigationHistory 属性访问（该属性在 web-contents.ts 中通过 Object.defineProperty 挂到 WebContents 原型上）。

其索引体系遵循顺序排列规则：

最早访问的页面在索引 0，最近访问的页面在索引 N（N = length() - 1）；
部分 API 接收 offset（偏移量）参数，表示相对于当前条目的位置：1 表示前进一页，-1 表示后退一页。

维护这份有序列表，使得浏览器式的前进/后退导航得以无缝进行。NavigationHistory 的全部实例方法如下（完整签名见 navigation-history.md）：

状态查询

方法	返回值	说明
`canGoBack()`	`boolean`	能否后退到上一页
`canGoForward()`	`boolean`	能否前进到下一页
`canGoToOffset(offset)`	`boolean`	能否前进/后退到相对当前条目 `offset` 处的条目
`getActiveIndex()`	`Integer`	当前页面在历史栈中的索引
`length()`	`Integer`	历史总长度
`getEntryAtIndex(index)`	`NavigationEntry` \| `null`	取指定索引处的条目；越界（小于 0 或大于历史长度）时返回 `null`
`getAllEntries()`	`NavigationEntry[]`	返回该 `webContents` 的完整历史数组

导航操作

方法	参数	说明
`goBack()`	-	后退一页
`goForward()`	-	前进一页
`goToIndex(index)`	`Integer`	跳转到指定的绝对索引位置
`goToOffset(offset)`	`Integer`	跳转到相对当前条目的相对偏移位置
`clear()`	-	清空导航历史
`removeEntryAtIndex(index)`	`Integer`	删除指定索引处的条目；不能删除"当前活动索引"处的条目，返回是否删除成功

底层实现：从 JS 字典到 content::NavigationEntry

NavigationEntry 在 JS 层是普通对象字典，在 C++ 层对应 Chromium 的 content::NavigationEntry。两者之间的桥梁是 gin 的类型转换器，其源码位于 electron_api_web_contents.cc：

JS → C++（FromV8）：

从字典中读取 url 与 title（二者均为必填，缺失即转换失败）；
若存在 pageState，先用 base::Base64Decode 解码，再通过 blink::PageState::CreateFromEncodedData 重建 blink::PageState 对象，并连同 NavigationEntryRestoreContext 一起挂到新建的 content::NavigationEntry 上；
解码或校验失败时直接返回 false，由上层按非法条目处理。

C++ → JS（ToV8）：

空指针返回 null（对应文档中"越界返回 null"的语义）；
写入 url（entry->GetURL().spec()）和 title（GetTitleForDisplay()）；
若 entry->GetPageState() 有效，则 Base64Encode(page_state.ToEncodedData()) 后写入 pageState 字段。

由此可以推断：getAllEntries() 返回的就是每个 content::NavigationEntry 经 ToV8 转换后的字典数组，天然可 JSON 序列化；而 restore() 时反向走 FromV8 重建原生条目。

几个值得注意的实现细节（见 electron_api_web_contents.cc）：

初始占位条目被过滤。GetHistory() 在历史长度为 1 且唯一条目是 Chromium 的 "InitialEntry"（尚无真实导航时的占位条目）时返回空数组——所以全新窗口的 getAllEntries() 是 [] 而不是含一条空记录。
恢复有严格前置条件。RestoreHistory() 会检查 GetLastCommittedEntry()->IsInitialEntry()：如果该 webContents 已经真实加载过任何页面，会抛出 "Cannot restore history on webContents that have previously loaded a page."。这与文档"建议在调用 loadURL()/loadFile() 之前调用"的建议完全一致。
恢复时自动携带 User-Agent 覆盖。重建条目时会取当前 webContents 的 UA，为每条 nav_entry 打上 SetIsOverridingUserAgent 标记，并在恢复后 SetUserAgentOverride，保证克隆出的窗口 UA 一致。
恢复流程。逐条转换后调用 GetController().Restore(index, content::RestoreType::kRestored, &entries) 重建整条历史链，再 LoadIfNecessary() 触发加载 index 指定的条目。

JS 侧的 restore() 封装（web-contents.ts）还做了参数规整：index 未提供时默认取 entries.length - 1（加载最新条目）；索引越界时抛出 Invalid index 错误；并预先通过 _awaitNextLoad(entries[index].url) 挂好加载 Promise——该 Promise 在页面完成加载（did-finish-load）后 resolve，加载失败（did-fail-load）时 reject，且已附带 noop rejection 处理以避免 unhandled rejection。

实战：跨窗口克隆导航历史（含表单值恢复）

以下示例综合了官方测试 api-web-contents-spec.ts 的验证流程，展示完整的"快照 → 关闭 → 恢复"闭环：

const { BrowserWindow } = require('electron');

(async () => {
  // 1. 原窗口中访问页面并修改表单
  const w = new BrowserWindow();
  await w.loadURL('https://example.com/1');
  await w.loadURL('https://example.com/2');
  await w.loadURL('https://example.com/form');

  // 修改表单值（Chromium 会在 unload 时/周期性提交 pageState）
  await w.webContents.executeJavaScript(
    'document.querySelector("input").value = "Hi!";'
  );

  // 触发一次新导航，确保修改后的 pageState 被提交
  await w.loadURL('https://example.com/3');

  // 2. 快照：整段历史可 JSON 序列化，便于持久化
  const entries = w.webContents.navigationHistory.getAllEntries();
  const persisted = JSON.stringify(entries); // 可写入文件/数据库

  // 3. 关闭原窗口，创建新窗口
  w.close();
  const w2 = new BrowserWindow();

  // 4. 在新窗口加载任何页面之前恢复历史
  //    index 指定最终停留在哪一条；不传则加载最新一条
  w2.webContents.navigationHistory.restore({
    index: 2,
    entries: JSON.parse(persisted)
  });

  // restore 返回的 Promise 在该条目完成加载后 resolve
  w2.webContents.once('dom-ready', async () => {
    const value = await w2.webContents.executeJavaScript(
      'document.querySelector("input")?.value'
    );
    console.log('表单值已恢复:', value); // 页面状态（滚动位置/表单值）已被还原
  });
})();

对健壮性的验证，官方测试覆盖了两种边界（见 api-web-contents-spec.ts）：

pageState 是非法 base64 时不会导致崩溃：转换阶段 Base64Decode 失败，恢复流程退化为仅用 url 和 title 重建条目，页面状态放弃还原但导航链完整；
User-Agent 覆盖可随历史一起恢复：测试用 session.fromPartition(...).setUserAgent('MyCustomUA') 后在新 WebContentsView 上 restore()，确认恢复出的 navigator.userAgent 与原窗口一致（api-web-contents-spec.ts）。

此外测试还验证了基础行为：连续加载 3 个页面后 getAllEntries() 按访问顺序返回 url 与 title 正确的 3 条记录；未加载任何页面时返回空数组；整组条目经过 JSON.stringify → JSON.parse 往返后与原值 deep.equal（api-web-contents-spec.ts）。

从旧版 webContents 导航 API 迁移

值得注意的是，NavigationHistory 的引入伴随着一组旧 API 的弃用。web-contents.ts 中通过 deprecate.warnOnce 为以下直接挂在 webContents 上的方法注册了弃用告警，并逐一给出新的导航入口：

已弃用	推荐替代
`webContents.canGoBack()`	`webContents.navigationHistory.canGoBack()`
`webContents.canGoForward()`	`webContents.navigationHistory.canGoForward()`
`webContents.canGoToOffset(offset)`	`webContents.navigationHistory.canGoToOffset(offset)`
`webContents.clearHistory()`	`webContents.navigationHistory.clear()`
`webContents.goBack()`	`webContents.navigationHistory.goBack()`
`webContents.goForward()`	`webContents.navigationHistory.goForward()`
`webContents.goToIndex(index)`	`webContents.navigationHistory.goToIndex(index)`
`webContents.goToOffset(offset)`	`webContents.navigationHistory.goToOffset(offset)`

新项目应直接使用 navigationHistory 命名空间；它除了收拢上述方法外，还新增了 getEntryAtIndex、removeEntryAtIndex、getAllEntries 与 restore 等"历史快照/恢复"能力，是 NavigationEntry 对象真正的消费方。

小结与使用边界

NavigationEntry（url / title / pageState）是 Chromium 导航条目在 JS 层的可序列化表示，pageState 承载滚动位置与表单值等页面状态；
只能通过 webContents.navigationHistory（主进程）访问，且 restore() 必须在该 webContents 首次加载任何页面前调用，否则底层会抛出异常；
pageState 是 Chromium 周期性/unload 时提交的快照，存在提交时机延迟，恢复表单值类状态时建议在读取历史前触发一次导航或用 did-finish-load 等事件对齐时机；
关键源码与测试索引：结构定义见 docs/api/structures/navigation-entry.md，类 API 见 docs/api/navigation-history.md，类型声明见 typings/internal-electron.d.ts，C++ 转换与恢复实现见 shell/browser/api/electron_api_web_contents.cc，行为验证见 spec/api-web-contents-spec.ts。