Push/pop stack（堆疊導航）

堆疊導航是最基本的模式。每次導航把新畫面推入堆疊頂端，按 back 彈出頂端畫面回到前一頁。使用者的心理模型是「深入 → 返回」的線性路徑。

適合場景：層級式的資訊結構（列表 → 詳細 → 編輯）、步驟式流程（填表 → 確認 → 完成）。

堆疊導航的限制是「只有一條軸」— 使用者只能在深度方向移動（往下鑽或往上回），無法在同層級的平行功能之間橫向切換。

Declarative router（宣告式路由）

Declarative router 用 URL 或路由路徑表示畫面狀態。Flutter 的 GoRouter、React Router、Vue Router 都屬於這個模式。導航操作是「把 URL 設成 /settings」而非「push SettingsScreen」。

Declarative router 的優勢是路由狀態和畫面狀態分離 — 路由邏輯集中管理，支援 deep link，支援動態重建導航堆疊（例如從 deep link 恢復完整的 back 堆疊）。

適合場景：需要 deep link 支援的 app、URL 驅動的 web app、複雜的條件式導航（根據使用者狀態決定顯示哪個畫面）。

Tab bar（標籤列導航）

畫面底部的標籤列讓使用者在平行的頂層功能之間橫向切換。每個 tab 是獨立的導航堆疊 — 在 tab A 深入到第三層，切換到 tab B 再切回 tab A，回到 tab A 的第三層。

適合場景：3-5 個平行的主要功能（首頁、搜尋、通知、個人檔案）。使用者頻繁在這些功能之間切換。

Tab bar 的限制是 tab 數量。超過 5 個 tab 在手機螢幕上過於擁擠。超過 5 個頂層功能時，次要功能放進「更多」tab 或改用 drawer。

Drawer（抽屜導航）

從螢幕邊緣滑出的側邊選單，列出所有導航選項。使用者需要打開 drawer 才能看到選項，日常操作中 drawer 是隱藏的。

適合場景：頂層功能超過 5 個、功能之間的切換頻率低、或需要顯示使用者資訊（帳號、設定）。

Drawer 的缺點是功能的可見性低 — 隱藏在側邊的功能不如 tab bar 上的功能容易被發現。不常用的功能適合放 drawer，核心功能應該放在更可見的位置。

組合使用

多數 app 組合使用多種導航模式。Tab bar 做頂層橫向導航，每個 tab 內部用 push/pop 做縱向深入，drawer 放使用者設定和次要功能。

組合使用時的注意點：back 按鈕的行為在不同模式下需要一致。在 tab A 的第三層按 back 應該回到第二層（push/pop 行為），而非切換到上一個 tab。

分類建立後，在 Flutter 的實作層面用 GoRouter 導航設計把導航模式對應到具體的 router 設定。不同導航操作（go / push / pushReplacement）的 UX 語意差異在 go vs push vs pushReplacement 語意表中逐一比對。確認導航實作正確後，用路由可達性檢查驗證所有路由從 UI 可達。

路由定義

GoRouter 的路由定義是一棵樹，每個節點是一個 GoRoute，指定 path 和 builder。

1GoRouter(routes: [
2  GoRoute(path: '/', builder: (context, state) => HomeScreen()),
3  GoRoute(path: '/enrollment', builder: (context, state) => EnrollmentScreen()),
4  GoRoute(path: '/terminal', builder: (context, state) => TerminalScreen()),
5]);

路由定義是 app 所有可到達畫面的完整清單。新增畫面時先在路由定義中加入 path，再實作 builder。路由定義同時也是路由可達性檢查的 source of truth（路由可達性）。

導航 API

GoRouter 提供三個主要的導航方法，語意不同，適用場景不同。

context.go(path)

替換整個導航堆疊。go('/terminal') 讓使用者直接到 terminal 畫面，按 back 不會回到前一個畫面（堆疊已被替換）。

適合場景：切換主要工作區。從登入畫面到首頁（登入成功後使用者不應該按 back 回到登入畫面）。

context.push(path)

把新畫面推入導航堆疊。push('/enrollment') 讓使用者到 enrollment 畫面，按 back 回到前一個畫面。

適合場景：暫時離開做一件事，做完回來。從首頁到配對畫面，配對完成後按 back 回首頁。

context.pushReplacement(path)

替換堆疊頂端的畫面。不改變堆疊深度 — 前一個畫面被新畫面取代，按 back 回到更早的畫面。

適合場景：步驟式流程中的前進。步驟 1 → pushReplacement 步驟 2 → pushReplacement 步驟 3。使用者在步驟 3 按 back 不會回到步驟 2（已被替換），而是回到流程開始前的畫面。

Redirect 機制

GoRouter 的 redirect 在每次導航前執行，可以根據 app 狀態（登入狀態、權限）把使用者導向不同畫面。

1GoRouter(
2  redirect: (context, state) {
3    final isLoggedIn = authState.isLoggedIn;
4    if (!isLoggedIn && state.matchedLocation != '/login') return '/login';
5    if (isLoggedIn && state.matchedLocation == '/login') return '/';
6    return null; // 不 redirect
7  },
8  routes: [...],
9);

Redirect 集中管理「什麼條件下使用者不能到某個畫面」的邏輯。比在每個畫面的 initState 中各自檢查更容易維護和測試。

ShellRoute（巢狀導航）

ShellRoute 讓多個畫面共享同一個外殼（tab bar、bottom navigation、drawer）。子路由的導航在 shell 內發生，shell 本身不變。

1ShellRoute(
2  builder: (context, state, child) => ScaffoldWithNavBar(child: child),
3  routes: [
4    GoRoute(path: '/home', builder: ...),
5    GoRoute(path: '/search', builder: ...),
6    GoRoute(path: '/profile', builder: ...),
7  ],
8)

ShellRoute 適合 tab bar 導航模式 — 底部的 tab bar 是 shell，每個 tab 的內容是子路由。

下一步路由

• go / push / pushReplacement 的 UX 語意 → go vs push vs pushReplacement 語意表
• iOS 和 Android 的導航差異 → iOS HIG vs Material Design 導航差異
• Deep link 設計 → Deep link 設計

Back 行為

iOS

iOS 沒有系統級的 back 按鈕。導航列左上角的 back 按鈕由 app 提供（UINavigationController 自動加入）。使用者也可以從螢幕左邊緣向右滑動觸發 back（edge swipe gesture）。

iOS 的 back 行為是 pop — 彈出堆疊頂端，回到前一個畫面。沒有 Android 的系統 back 按鈕覆寫機制。

Android / Material Design

Android 有系統級的 back 按鈕（虛擬或實體）。Material Design 在 app bar 左上角也放 back 箭頭或 hamburger menu 圖示。

Android 的 back 行為由 app 控制（onBackPressed），可以被覆寫。常見的覆寫場景：在首頁按 back 詢問「是否離開 app」、在表單中按 back 詢問「是否放棄編輯」。

跨平台決策

Flutter 預設在 Android 上攔截系統 back 按鈕，在 iOS 上提供 back 按鈕和 edge swipe。GoRouter 的 pop() 在兩個平台上行為一致。

跨平台 app 需要注意的差異：iOS 使用者習慣 edge swipe back，Android 使用者習慣按系統 back 按鈕。兩者都要支援。

Tab bar 位置

iOS

Tab bar 固定在畫面底部。iOS 使用者期望 tab bar 永遠可見、永遠在底部。Apple 的 HIG 明確建議 tab bar 在底部。

Material Design

Material Design 的 bottom navigation 也在底部，但額外支援 top tabs（在 app bar 下方的可滑動標籤列）。Top tabs 適合同一類內容的不同視角（全部 / 未讀 / 已標記）。

跨平台決策

底部 tab bar 在兩個平台上都是標準做法。Top tabs 在 iOS 上較少見（iOS 偏好用 segmented control 代替 top tabs）。跨平台 app 用底部 tab bar 是最安全的選擇。

Modal 呈現

iOS

iOS 的 modal 畫面從底部滑上來，覆蓋前一個畫面但不完全遮擋（iOS 13+ 的 sheet 呈現樣式可以看到前一個畫面的上緣）。Dismiss 操作是向下滑動或點擊關閉按鈕。

Material Design

Material Design 的 bottom sheet 和 dialog 是 modal 的主要形式。Full-screen dialog 從底部滑上來，有 close 按鈕在左上角和 action 按鈕在右上角。

跨平台決策

Flutter 的 showModalBottomSheet 和 showDialog 在兩個平台上都可用。視覺呈現可以用 platform-adaptive widget（CupertinoPageRoute vs MaterialPageRoute）按平台切換。

選擇策略

多數跨平台 app 選擇「共用核心、差異點適配」— 底部 tab bar、push/pop 導航在兩個平台上一致；back 手勢、modal 呈現按平台適配。

下一步路由

• Deep link 設計 → Deep link 設計
• go vs push 的語意差異 → go vs push vs pushReplacement 語意表
• 導航模式分類 → Mobile 導航模式分類

三種 deep link 機制

Custom URL scheme

App 註冊自訂的 URL scheme（myapp://），系統收到這個 scheme 的 URL 時打開 app。myapp://terminal?host=192.168.1.100 打開 app 的 terminal 畫面。

Custom URL scheme 的限制：沒有 ownership 驗證（任何 app 都可以註冊 myapp://），只在 app 已安裝時有效（未安裝時 URL 無效），不適合 web 分享（瀏覽器無法開啟 myapp://）。

Universal Link（iOS）/ App Link（Android）

App 宣告擁有特定 domain 的 URL（https://example.com/terminal）。系統驗證 domain 的 ownership（domain 上放 .well-known/apple-app-site-association 或 assetlinks.json），驗證通過後這些 URL 直接在 app 中打開。

優勢：使用標準 HTTPS URL（可以在瀏覽器中分享）、有 ownership 驗證（防止冒充）、app 未安裝時 fallback 到網頁。

Deferred deep link

使用者點擊 deep link 時 app 未安裝。系統引導使用者到 app store 安裝，安裝後首次開啟時自動導航到 deep link 指定的畫面。

Deferred deep link 需要第三方服務（Firebase Dynamic Links、Branch）或自建機制在安裝前後傳遞 URL 參數。

URL 結構設計

Deep link 的 URL 結構應該和 GoRouter 的路由定義一致。GoRouter 原生支援 deep link — URL path 就是路由 path。

1https://example.com/terminal        → TerminalScreen
2https://example.com/enrollment      → EnrollmentScreen
3https://example.com/terminal?host=x → TerminalScreen(host: x)

URL 參數（query parameters）傳遞畫面需要的資料。參數值避免包含敏感資訊 — URL 可能被系統日誌、分析工具、中間人記錄。

導航堆疊重建

使用者從 deep link 直接進入 /terminal 畫面時，導航堆疊中沒有首頁。使用者按 back 應該回到首頁還是離開 app？

重建完整堆疊

GoRouter 的 go('/terminal') 可以設定為自動把前置路由放入堆疊。使用者按 back 回到首頁，再按 back 離開 app。使用者的心理模型是「deep link 帶我到這個畫面，back 帶我到 app 的正常入口」。

只放 deep link 目標

堆疊中只有 deep link 目標畫面。按 back 離開 app。適合「一次性操作」的 deep link（打開 → 操作 → 離開）。

選擇策略

如果 deep link 的畫面是 app 日常使用的一部分，重建完整堆疊讓使用者能繼續在 app 中操作。如果 deep link 是從外部觸發的獨立操作（掃描 QR code → 顯示結果），只放目標畫面更簡潔。

Deep link 測試

Deep link 需要端對端測試 — 從外部觸發 URL，驗證 app 導航到正確畫面。

測試項目：

• 每個路由的 deep link 能正確打開
• URL 參數正確傳遞到畫面
• App 在前景、背景、未啟動三種狀態下都能處理 deep link
• 無效的 deep link URL 有合理的 fallback（導航到首頁或顯示錯誤）
• Universal Link 的 domain verification 正確

Deep link 的實作在 Flutter 中由 GoRouter 的 route matching 處理 — Flutter GoRouter 導航設計包含 deep link 的設定方式。Deep link 觸發的導航操作（go vs push）影響使用者的返回路徑，語意差異見 go vs push vs pushReplacement 語意表。Deep link 的端對端驗證在 testing 模組四 自動化 UI 驗證中歸類到導航路徑 test。

語意對照表

go：切換工作區

go 把整個導航堆疊替換成新的路徑。使用者按 back 不會回到操作前的畫面，因為堆疊已經被替換。

適合場景：

• 登入成功後到首頁（使用者不應該按 back 回到登入畫面）
• 登出後到登入畫面（使用者不應該按 back 回到需要認證的畫面）
• 從 onboarding 到主畫面（onboarding 完成後不需要回去）

誤用 go 的後果：使用者期望按 back 回到前一個畫面但堆疊已空，按 back 直接離開 app。app_tunnel 修復時選擇 push('/enrollment') 而非 go('/enrollment')，讓使用者配對完成後能按 back 回首頁（U.C4）。

push：暫時離開，做完回來

push 在堆疊頂端加入新畫面。使用者按 back 回到前一個畫面。

適合場景：

• 從列表到詳細頁（看完回到列表）
• 從首頁到配對畫面（配對完回首頁）
• 從任何畫面到設定頁（改完設定回原畫面）

push 是最常用的導航方法，因為多數導航都是「暫時去另一個畫面做事，做完回來」的模式。

pushReplacement：流程中前進

pushReplacement 用新畫面替換堆疊頂端。堆疊深度不變，按 back 回到替換前畫面的前一個畫面（跳過被替換的畫面）。

適合場景：

• 步驟式流程：步驟 1 → pushReplacement 步驟 2 → pushReplacement 步驟 3。使用者在步驟 3 按 back 回到流程開始前的畫面，不會回到步驟 2 或 1。
• 結果頁替換搜尋頁：搜尋結果替換搜尋條件頁，使用者按 back 回到搜尋前的畫面。

pushReplacement 的語意是「這一步完成後使用者不需要回到這裡」。用於不可回退的流程步驟。

選擇決策流程

對每個導航操作問一個問題：使用者按 back 時，期望回到哪裡？

• 回到前一個畫面 → push
• 離開 app 或回到 app 的根畫面 → go
• 跳過當前畫面，回到更早的畫面 → pushReplacement

這個決策應該在 UX 設計階段做，記錄在畫面狀態矩陣的「退出路徑」欄中。開發者實作時對照矩陣選擇正確的導航方法。

常見誤用

用 go 做應該用 push 的導航

「首頁 → 配對畫面」如果用 go，使用者配對完成後按 back 離開 app 而非回到首頁。使用者期望的是「配對完成回首頁」（push 行為）。

用 push 做應該用 go 的導航

「登入 → 首頁」如果用 push，使用者在首頁按 back 回到登入畫面。使用者已經登入，不應該看到登入畫面。

用 push 做應該用 pushReplacement 的導航

步驟式流程中「步驟 1 → 步驟 2」如果用 push，使用者在步驟 2 按 back 回到步驟 1。如果步驟 1 的操作不可逆（已經提交了資料），回到步驟 1 沒有意義。

下一步路由

• Flutter GoRouter 的完整導航 API → Flutter GoRouter 導航設計
• 導航模式分類 → Mobile 導航模式分類
• 路由可達性檢查 → ux-design 模組一 路由可達性
• 導航路徑的自動化測試 → testing 模組四 自動化 UI 驗證