react-router-framework-mode

React Router 框架模式

框架模式是 React Router 的全端開發體驗，包含基於檔案的路由、伺服器端、客戶端與靜態渲染策略、資料載入與變更，以及型別安全的路由模組 API。

何時套用

• 設定新路由（app/routes.ts）
• 使用 loader 或 clientLoader 載入資料
• 使用 action 或 clientAction 處理變更
• 使用 <Link>、<NavLink>、<Form>、redirect 和 useNavigate 進行導航
• 實作待處理/載入中 UI 狀態
• 設定 SSR、SPA 模式或預先渲染（react-router.config.ts）
• 實作驗證

參考資料

載入相關參考資料以取得特定 API/概念的詳細指引：

參考資料	使用時機
references/routing.md	設定路由、巢狀路由、動態區段
references/route-modules.md	了解所有路由模組匯出
references/special-files.md	自訂 root.tsx、加入全域導航/頁尾、字型
references/data-loading.md	使用 loader 載入資料、串流、快取
references/actions.md	處理表單、變更、驗證
references/navigation.md	連結、程式化導航、重新導向
references/pending-ui.md	載入狀態、樂觀 UI
references/error-handling.md	錯誤邊界、錯誤回報
references/rendering-strategies.md	SSR vs SPA vs 預先渲染設定
references/middleware.md	加入中介軟體（需要 v7.9.0+）
references/sessions.md	Cookie 工作階段、驗證、受保護路由
references/type-safety.md	自動產生的路由型別、型別匯入、型別安全

版本相容性

某些功能需要特定 React Router 版本。實作前務必確認：

npm list react-router

功能	最低版本	備註
中介軟體	7.9.0+	需要 v8_middleware 旗標
核心框架功能	7.0.0+	loaders、actions、Form 等

關鍵模式

這些是最重要的模式。載入相關參考資料以取得完整細節。

表單與變更

搜尋表單 - 使用 <Form method="get">，不要使用 onSubmit 搭配 setSearchParams：

// ✅ 正確
<Form method="get">
  <input name="q" />
</Form>

// ❌ 錯誤 - 不要手動處理搜尋參數
<form onSubmit={(e) => { e.preventDefault(); setSearchParams(...) }}>

內聯變更 - 使用 useFetcher，不要使用 <Form>（會導致頁面導航）：

const fetcher = useFetcher();
const optimistic = fetcher.formData?.get("favorite") === "true" ?? isFavorite;

<fetcher.Form method="post" action={`/favorites/${id}`}>
  <button>{optimistic ? "★" : "☆"}</button>
</fetcher.Form>;

完整模式請參閱 references/actions.md。

佈局

全域 UI 應放在 root.tsx - 不要為導航/頁尾建立獨立的佈局檔案：

// app/root.tsx - 在此加入導航、頁尾、提供者
export default function App() {
  return (
    <div>
      <nav>...</nav>
      <Outlet />
      <footer>...</footer>
    </div>
  );
}

使用巢狀路由 處理區段專屬佈局。請參閱 references/routing.md。

路由模組匯出

meta 使用 loaderData，不要使用已棄用的 data：

// ✅ 正確
export function meta({ loaderData }: Route.MetaArgs) { ... }

// ❌ 錯誤 - `data` 已棄用
export function meta({ data }: Route.MetaArgs) { ... }

所有匯出請參閱 references/route-modules.md。

更多文件

如果這些參考資料未涵蓋任何與 React Router 相關的內容，您可以搜尋官方文件：

https://reactrouter.com/docs