在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

remix-run/react-router

菜单

数据 API

相关源文件

React Router 的数据 API 提供了一个全面的系统，用于在您的应用程序中加载、修改和管理数据。这些 API 支持与路由直接绑定的声明式数据处理，从而实现优化的加载模式、后台获取和结构化的错误处理。

如果您正在寻找服务器端渲染的详细信息，请参阅 服务器端渲染。有关特定于平台的 D数据处理实现，请参阅 平台适配。

来源： packages/react-router/lib/router/router.ts285-396 packages/react-router/lib/hooks.tsx72-431

核心数据架构

React Router 的数据 API 构建在一个有状态的路由器之上，该路由器管理数据加载、修改和错误状态。该路由器维护已加载数据、表单提交结果和后台操作的状态，然后通过专门的钩子（hooks）由 React 组件使用。

来源： packages/react-router/lib/router/router.ts282-357 packages/react-router/lib/router/utils.ts186-267

加载器与操作

Loader（加载器）和 Action（动作）是 React Router 中处理数据的首选方法。它们提供了一种结构化的方法来获取和修改数据，并与路由系统紧密集成。

加载器

Loader 是路由特定的函数，在渲染路由时加载数据。它们在导航期间、组件渲染之前执行，确保数据在路由显示时即可获得。

Loader 在以下场景执行：

  1. 初始页面加载
  2. 客户端导航到新路由
  3. 手动重新验证时
  4. Action 提交后

useLoaderData 钩子使组件能够访问路由 loader 返回的数据。

来源： packages/react-router/lib/router/utils.ts232-258 packages/react-router/lib/hooks.tsx350-429

操作

Actions 处理 React Router 中的数据修改和表单提交。它们在表单提交期间在 loaders 之前运行，允许您在刷新 UI 状态之前更新服务器状态。

Actions 由以下方式触发：

  1. 表单提交（<Form> 组件）
  2. 以编程方式提交（useSubmit 钩子）
  3. Fetcher 提交（fetcher.Form 或 fetcher.submit）

Action 完成后：

  1. 路由器通过调用受影响路由的 loaders 来重新验证数据。
  2. 组件可以通过 useActionData 钩子访问 Action 结果。

来源： packages/react-router/lib/router/utils.ts259-267 packages/react-router/lib/hooks.tsx430-500

表单处理

React Router 提供了增强的表单处理功能，可与 Action 系统集成。表单可以使用各种方法、编码和数据格式进行提交。

表单提交类型

来源： packages/react-router/lib/router/utils.ts55-114 packages/react-router/lib/dom/lib.tsx480-650

表单提交可以具有不同的编码类型：

  • application/x-www-form-urlencoded (默认)
  • multipart/form-data (用于文件上传)
  • application/json (用于 JSON 数据)
  • text/plain (用于纯文本)

来源： packages/react-router/lib/dom/lib.tsx930-1025 packages/react-router/lib/router/utils.ts71-75

Fetcher（获取器）

Fetchers 提供了一种在不触发导航的情况下与路由加载器和 Action 进行交互的方法。这对于不应影响当前页面的后台数据操作很有用。

来源： packages/react-router/lib/router/router.ts574-650 packages/react-router/lib/dom/lib.tsx1450-1700

使用 Fetchers

Fetchers 使用 useFetcher 钩子创建，它返回一个包含加载数据、提交表单和检查当前状态的方法的对象。

Fetchers 维护自己的独立于导航的加载状态。

  • fetcher.state：当前的 fetcher 状态（"idle"（空闲）、"loading"（加载中）或 "submitting"（提交中））。
  • fetcher.data：上次成功加载或 Action 调用返回的数据。
  • fetcher.formData：当前提交的表单数据。
  • fetcher.formMethod：用于当前操作的 HTTP 方法。

来源： packages/react-router/lib/dom/lib.tsx1500-1600 packages/react-router/lib/__tests__/fetchers-test.ts1-200

错误处理

React Router 提供了一个强大的错误处理系统，可以捕获渲染、数据加载和 Action 期间的错误。错误会自动沿路由层级向上传播，直到遇到错误边界。

来源： packages/react-router/lib/context.ts200-204 packages/react-router/lib/hooks.tsx700-750

错误边界

错误边界通过 errorElement prop 或 ErrorBoundary 组件在路由上定义。

当发生错误时，React Router 将：

  1. 停止渲染路由的常规组件。
  2. 改为渲染最近的错误边界。
  3. 通过 useRouteError 钩子提供错误信息。

来源： packages/react-router/lib/dom/ssr/routes.tsx68-83 packages/react-router/lib/components.tsx98-132

抛出 Responses（响应）

React Router 允许您从 loaders 和 actions 抛出 responses 来指示特定的错误条件。

这些 responses 会被路由系统捕获并妥善处理，对于错误 responses 会渲染错误边界，对于重定向 responses 会执行重定向。

来源： packages/react-router/lib/router/utils.ts782-866 packages/react-router/lib/__tests__/router/redirects-test.ts1-50

数据策略

React Router 提供可自定义的数据加载策略，默认是并行加载。数据策略控制路由数据的加载方式和时间。

来源： packages/react-router/lib/router/utils.ts4000-4200 packages/react-router/__tests__/router/data-strategy-test.ts1-50

默认策略（并行加载）

默认情况下，React Router 会并行加载所有需要数据的路由。这通过同时获取所有必需的数据来最大化性能。

来源： packages/react-router/lib/router/router.ts4000-4200 packages/react-router/__tests__/router/data-strategy-test.ts35-75

单次获取策略

对于服务器渲染的应用，React Router 提供了一个“单次请求”策略，通过将多个 loader 请求合并为一个 HTTP 请求来优化数据加载。

此策略对于服务器端渲染特别有用，它可以减少客户端和服务器之间的往返次数。

来源： packages/react-router/index.ts354-355 packages/react-router/__tests__/router/data-strategy-test.ts200-250

自定义数据策略

您可以为专门的加载模式实现自定义数据策略。

来源： packages/react-router/lib/components.tsx173-206 packages/react-router/__tests__/router/data-strategy-test.ts35-60

数据钩子

React Router 提供了一组钩子来访问由 loader 和 action 加载的数据。

核心数据钩子

钩子描述用途
useLoaderData()访问当前路由 loader 的数据const data = useLoaderData()
useActionData()访问上一次 action 提交的数据const actionData = useActionData()
useRouteLoaderData(routeId)通过 ID 访问任何路由 loader 的数据const parentData = useRouteLoaderData("parent")
useRouteError()访问最近的错误边界捕获的错误const error = useRouteError()
useNavigation()访问当前导航状态const navigation = useNavigation()
useRevalidator()手动触发数据重新验证const { revalidate } = useRevalidator()
useFetcher()为后台操作创建 fetcherconst fetcher = useFetcher()

来源： packages/react-router/lib/hooks.tsx350-700 packages/react-router/index.ts122-142

数据访问模式

来源： packages/react-router/lib/hooks.tsx350-600 packages/react-router/__tests__/data-memory-router-test.tsx20-160

与服务器端渲染集成

React Router 的数据 API 与服务器端渲染无缝集成，允许在服务器上预加载数据，并在客户端进行水合，而无需额外的获取。

来源： packages/react-router/lib/dom/server.tsx1-100 packages/react-router/lib/router/router.ts360-380

在服务器端渲染期间

  1. 服务器匹配路由并执行 loader
  2. 数据被序列化并包含在 HTML 响应中
  3. 客户端使用此水合数据创建路由器
  4. 组件立即使用预加载的数据进行渲染

此过程消除了如果数据需要在初始渲染后获取而可能出现的“加载闪烁”。

来源： packages/react-router/lib/components.tsx400-500 packages/react-router/__tests__/dom/partial-hydration-test.tsx1-100

高级特性

数据上下文和中间件

React Router 支持数据处理中的上下文和中间件（目前标记为不稳定）

来源： packages/react-router/lib/router/utils.ts116-174 packages/react-router/__tests__/router/context-middleware-test.ts41-100

延迟路由加载

React Router 支持延迟加载路由及其数据处理函数

基于对象的这种方法允许精细控制何时加载不同部分的路由，这可以通过仅在需要时加载所需内容来提高性能。

来源： packages/react-router/__tests__/router/lazy-test.ts38-70 packages/react-router/lib/dom/ssr/routes.tsx130-160

结论

React Router 的数据 API 提供了一个全面的系统，用于在应用程序中加载、修改和管理数据。通过将数据处理直接与路由集成，React Router 创建了一个统一的状态管理模式，该模式同时适用于客户端和服务器。

这些 API 实现了声明式数据处理、优化的加载模式和结构化的错误管理，使您能够构建具有清晰关注点分离的健壮 Web 应用程序。

来源： packages/react-router/lib/router/router.ts282-357 packages/react-router/lib/hooks.tsx72-142