react-router-framework-mode

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

React Router Framework Mode

React Router 框架模式

Framework mode is React Router's full-stack development experience with file-based routing, server-side, client-side, and static rendering strategies, data loading and mutations, and type-safe route module API.

框架模式是React Router的全栈开发体验，支持基于文件的路由、服务端/客户端/静态渲染策略、数据加载与变更，以及类型安全的路由模块API。

When to Apply

适用场景

Configuring new routes (
```
app/routes.ts
```
)
Loading data with
```
loader
```
or
```
clientLoader
```
Handling mutations with
```
action
```
or
```
clientAction
```

Navigating with

<Link>

<NavLink>

<Form>

redirect

, and

useNavigate

Implementing pending/loading UI states
Configuring SSR, SPA mode, or pre-rendering (
```
react-router.config.ts
```
)
Implementing authentication

配置新路由（
```
app/routes.ts
```
）
使用
```
loader
```
或
```
clientLoader
```
加载数据
使用
```
action
```
或
```
clientAction
```
处理数据变更

使用

<Link>

、

<NavLink>

、

<Form>

、

redirect

和

useNavigate

进行导航

实现待处理/加载UI状态
配置SSR、SPA模式或预渲染（
```
react-router.config.ts
```
）
实现认证功能

References

参考文档

Load the relevant reference for detailed guidance on the specific API/concept:

Reference	Use When
`references/routing.md`	Configuring routes, nested routes, dynamic segments
`references/route-modules.md`	Understanding all route module exports
`references/special-files.md`	Customizing root.tsx, adding global nav/footer, fonts
`references/data-loading.md`	Loading data with loaders, streaming, caching
`references/actions.md`	Handling forms, mutations, validation
`references/navigation.md`	Links, programmatic navigation, redirects
`references/pending-ui.md`	Loading states, optimistic UI
`references/error-handling.md`	Error boundaries, error reporting
`references/rendering-strategies.md`	SSR vs SPA vs pre-rendering configuration
`references/middleware.md`	Adding middleware (requires v7.9.0+)
`references/sessions.md`	Cookie sessions, authentication, protected routes
`references/type-safety.md`	Auto-generated route types, type imports, type safety

加载相关参考文档以获取特定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、SPA与预渲染的配置对比
`references/middleware.md`	添加中间件（需要v7.9.0+版本）
`references/sessions.md`	Cookie会话、认证、受保护路由
`references/type-safety.md`	自动生成路由类型、类型导入、类型安全

Version Compatibility

版本兼容性

Some features require specific React Router versions. Always verify before implementing:

bash

npm list react-router

Feature	Minimum Version	Notes
Middleware	7.9.0+	Requires `v8_middleware` flag
Core framework features	7.0.0+	loaders, actions, Form, etc.

部分功能需要特定的React Router版本。在实现前请务必验证：

bash

npm list react-router

功能	最低版本要求	说明
中间件	7.9.0+	需要启用 `v8_middleware` 标志
核心框架特性	7.0.0+	包括loader、action、Form等

Critical Patterns

关键模式

These are the most important patterns to follow. Load the relevant reference for full details.

以下是需要遵循的最重要模式。加载相关参考文档以获取完整细节。

Forms & Mutations

表单与数据变更

Search forms - use

<Form method="get">

, NOT

onSubmit

with

setSearchParams

tsx

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

// ❌ Wrong - don't manually handle search params
<form onSubmit={(e) => { e.preventDefault(); setSearchParams(...) }}>

Inline mutations - use

useFetcher

, NOT

<Form>

(which causes page navigation):

tsx

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

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

See

references/actions.md

for complete patterns.

搜索表单 - 使用

<Form method="get">

，而非带

setSearchParams

的

onSubmit

：

tsx

// ✅ 正确写法
<Form method="get">
  <input name="q" />
</Form>

// ❌ 错误写法 - 不要手动处理搜索参数
<form onSubmit={(e) => { e.preventDefault(); setSearchParams(...) }}>

内联数据变更 - 使用

useFetcher

，而非

<Form>

（后者会导致页面导航）：

tsx

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

。

Layouts

布局

Global UI belongs in
root.tsx
- don't create separate layout files for nav/footer:

tsx

// app/root.tsx - add navigation, footer, providers here
export default function App() {
  return (
    <div>
      <nav>...</nav>
      <Outlet />
      <footer>...</footer>
    </div>
  );
}

Use nested routes for section-specific layouts. See

references/routing.md

全局UI应放在
root.tsx
中 - 不要为导航/页脚创建单独的布局文件：

tsx

// app/root.tsx - 在此处添加导航、页脚、提供者
export default function App() {
  return (
    <div>
      <nav>...</nav>
      <Outlet />
      <footer>...</footer>
    </div>
  );
}

使用嵌套路由实现特定板块的布局。详情请查看

references/routing.md

。

Route Module Exports

路由模块导出

meta
uses
loaderData
, not deprecated

data

tsx

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

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

See

references/route-modules.md

for all exports.

meta
使用
loaderData
，而非已弃用的

data

：

tsx

// ✅ 正确写法
export function meta({ loaderData }: Route.MetaArgs) { ... }

// ❌ 错误写法 - `data`已被弃用
export function meta({ data }: Route.MetaArgs) { ... }

所有导出项请查看

references/route-modules.md

。