Navigation API 怎麼取代 pushState？SPA 先處理 navigate 與 fallback

Navigation API 解決的是哪一層#

先把幾個責任分開：

這個 API 管理的是瀏覽器的 navigation 與 history 生命週期，不是替你決定 URL 對應哪個元件。路由表、資料取得、快取和畫面更新仍然要由應用程式或框架處理。

先用 feature detection 接上 navigate#

下面是以原生 JavaScript 寫的最小骨架。renderDocument() 代表你的畫面更新函式；實際專案應另外處理 title、focus、scroll restoration、錯誤畫面和快取。

1
const appNavigation = globalThis.navigation;
2

3
if (appNavigation) {
4
  appNavigation.addEventListener('navigate', (event) => {
5
    if (
6
      !event.canIntercept ||
7
      event.hashChange ||
8
      event.downloadRequest ||
9
      event.formData
10
    ) {
11
      return;
12
    }
13

14
    const url = new URL(event.destination.url);
15
    if (url.origin !== location.origin) {
16
      return;
17
    }
18

19
    event.intercept({
20
      async handler() {
21
        const response = await fetch(url, {
22
          headers: { Accept: 'text/html' },
23
          signal: event.signal,
24
        });
25

26
        if (!response.ok) {
27
          throw new Error('Navigation failed: ' + response.status);
28
        }
29

30
        renderDocument(await response.text(), url);
31
      },
32
    });
33
  });
34
}

event.canIntercept 先排除瀏覽器不允許頁面接管的導覽；hashChange 保留原生的同頁錨點行為；downloadRequest 和 formData 則避免把下載或非 GET 表單錯當成純頁面切換。event.signal 讓 fetch 可以在下一次導覽取代目前請求時中止。

不要把所有 navigate 都攔下來。跨來源連結、下載、檔案上傳和需要完整 document navigation 的情況，讓瀏覽器照原本的方式處理通常更可靠。

intercept() 後要管理兩個完成時機#

event.intercept({ handler }) 接管後，handler 的成功或失敗會影響 navigation 的結果。畫面開始切換與資料真的完成不是同一件事，因此程式導覽可以拆開等待：

1
const result = globalThis.navigation.navigate('/settings');
2

3
result.committed
4
  .then(() => showRouteLoadingState())
5
  .catch((error) => showRouteError(error));
6

7
result.finished
8
  .then(() => recordRouteReady())
9
  .catch((error) => recordRouteFailure(error));

committed 適合用來表示 history entry 已經提交、畫面可以進入切換狀態；finished 則適合收尾 metrics、focus 或 loading indicator。兩者都要處理 rejection，否則使用者看到的可能是已經改變 URL，畫面卻停在半完成狀態。

保留 pushState fallback#

Navigation API 雖然已進入 Baseline 2026，專案仍可能需要支援沒有 globalThis.navigation 的執行環境。把程式導覽包在一個小函式中，就能讓新舊路徑共用呼叫端：

1
function navigateTo(path) {
2
  const target = new URL(path, location.href);
3

4
  if (globalThis.navigation) {
5
    return globalThis.navigation.navigate(target.href).finished;
6
  }
7

8
  history.pushState(null, '', target.href);
9
  window.dispatchEvent(new PopStateEvent('popstate'));
10
  return Promise.resolve();
11
}

fallback 不是把兩套 router 永久並行，而是讓 migration 有一個清楚的邊界：支援 Navigation API 的瀏覽器走 navigate，其他環境保留既有 popstate renderer。當框架本身已經擁有 router 時，應先確認它是否已接管 navigation event，避免在 framework router 外再攔一次。

初次載入和同源限制不能忽略#

Navigation API 不會因為頁面第一次載入就送出 navigate event。使用者直接開啟深層 URL、重新整理或從外部網站進入時，仍需要 server 回傳正確 document，或由既有 hydration／bootstrap 讀取目前 URL。只在 client listener 裡宣告路由，不能取代 SSR、靜態 fallback 或 server rewrite。

另外，這個 API 的可攔截範圍以目前 browsing context 的同源 navigation 為中心，並且是 frame-local。它不會讓頁面任意改寫瀏覽器 history，也不會把跨來源頁面變成同一個 SPA route。實作時至少要保留：

• server 對每個可分享 URL 的直接回應。
• 跨來源、下載、檔案上傳和非頁面導覽的原生行為。
• 同一個 tab、iframe 或 nested browsing context 的路由邊界。
• route handler 失敗時的 navigateerror、重試與可理解錯誤畫面。

從舊 router 遷移的順序#

若現有程式已經大量使用 pushState，可以分階段移動：

1. 先把 route table 和 render 函式從 click handler 抽出來。
2. 將同源的 anchor navigation 接到 navigate，保留原本的 popstate 作為 fallback。
3. 用 event.canIntercept、hashChange、downloadRequest 和 formData 建立拒絕清單。
4. 將資料請求綁定 event.signal，測試快速連點、返回／前進與請求取消。
5. 最後才把程式導覽改成 navigation.navigate()，並記錄 committed／finished 的錯誤。

這個順序讓 navigation semantics 先穩定，再替換 API 呼叫。不要一次把 history、資料載入、View Transition 和整個 component lifecycle 同時重寫，否則遇到返回按鈕問題時很難知道是哪一層回歸。

常見問題#