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	使用加载器加载数据、流式传输和缓存
references/actions.md	处理表单、变更和验证
references/navigation.md	链接、编程式导航和重定向
references/pending-ui.md	加载状态和乐观 UI
references/error-handling.md	错误边界和错误报告
references/rendering-strategies.md	SSR、SPA 与预渲染配置
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">，不要使用带有 setSearchParams 的 onSubmit：

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

// ❌ Wrong - don't manually handle search params
<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 - add navigation, footer, providers here
export default function App() {
  return (
    <div>
      <nav>...</nav>
      <Outlet />
      <footer>...</footer>
    </div>
  );
}

使用嵌套路由实现特定于区域的布局。请参阅 references/routing.md。

路由模块导出

meta 使用 loaderData，而非已弃用的 data：

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

// ❌ Wrong - `data` is deprecated
export function meta({ data }: Route.MetaArgs) { ... }

所有导出请参阅 references/route-modules.md。

更多文档

如果这些参考资料未涵盖 React Router 相关内容，可以搜索官方文档：

https://reactrouter.com/docs