核心组件

相关源文件

• .eslintignore
• .gitignore
• CONTRIBUTING.md
• README.md
• docs/api/components/Link.md
• docs/api/components/Route.md
• docs/api/components/Routes.md
• docs/api/index.md
• examples/README.md
• package.json
• packages/react-router/__tests__/data-memory-router-test.tsx
• packages/react-router/index.ts
• packages/react-router/lib/components.tsx
• packages/react-router/lib/context.ts
• packages/react-router/lib/dom/lib.tsx
• packages/react-router/lib/hooks.tsx

本页面文档记录了构成 React Router 组件 API 的主要组件。这些组件是定义路由、处理导航以及根据当前 URL 渲染相应 UI 元素的构建块。

有关数据加载和数据修改功能的信息，请参阅 数据 API。有关服务器端渲染的详细信息，请参阅 服务器端渲染。

Router 组件概述

React Router 的基础是 Router 组件，它为所有其他组件提供了路由上下文。大多数应用程序不直接使用基础的 Router，而是使用特定于环境的实现或数据路由器 API 和 RouterProvider。

来源： packages/react-router/lib/components.tsx751-825 packages/react-router/lib/components.tsx521-559 packages/react-router/lib/dom/lib.tsx303-336 packages/react-router/lib/dom/lib.tsx353-382 packages/react-router/lib/components.tsx243-489

基础 Router

Router 组件是低级接口，为应用程序的其余部分提供路由上下文。它负责：

1. 建立导航上下文
2. 为子组件提供 location 上下文
3. 确保应用程序中只有一个 router

在大多数情况下，不应直接使用 Router 组件。而是使用像 BrowserRouter、HashRouter 这样的更高级别 Router，或者使用 RouterProvider 和数据路由器 API。

来源： packages/react-router/lib/components.tsx751-825

特定环境的 Router

React Router 提供了特定于环境的 Router 实现：

• BrowserRouter：在 Web 浏览器中使用 HTML5 history API 实现干净的 URL。
• HashRouter：使用 URL hash 进行路由（适用于静态文件托管）。
• MemoryRouter：将 history 保存在内存中（适用于测试和非浏览器环境）。
• RouterProvider：与 createBrowserRouter、createHashRouter 等创建的数据路由器一起使用。

来源： packages/react-router/lib/dom/lib.tsx303-336 packages/react-router/lib/dom/lib.tsx353-382 packages/react-router/lib/components.tsx521-559 packages/react-router/lib/components.tsx243-489

路由定义组件

任何 React Router 应用的核心是如何定义路由。React Router 为此提供了两个主要组件：Routes 和 Route。

来源： packages/react-router/lib/components.tsx859-864 packages/react-router/lib/components.tsx722-728 packages/react-router/lib/context.ts24-68

Routes 组件

Routes 组件是 Route 组件的容器。它渲染与当前 URL 匹配的第一个 Route。与 v5 中的旧 Switch 组件不同，Routes 会自动处理相对路径和嵌套路由。

主要功能

• 自动查找最佳匹配路由
• 支持嵌套路由
• 可以接受 location 属性来覆盖当前 location（对于动画或待处理的导航状态很有用）。

来源： packages/react-router/lib/components.tsx859-864 docs/api/components/Routes.md1-40

Route 组件

Route 组件定义了应用程序中的单个路由。它将 URL 路径映射到组件。路由可以嵌套以创建分层的 UI。

关键属性

• path：要匹配的 URL 模式（支持动态段，如 :id）。
• element/Component：匹配路由时要渲染的内容。
• errorElement/ErrorBoundary：发生错误时要渲染的内容。
• index：将此路由指定为父路由的默认“索引”路由。
• caseSensitive：是否区分大小写匹配路径。
• loader、action：对于数据路由器，这些用于处理数据加载和修改。

来源： packages/react-router/lib/components.tsx722-728 packages/react-router/lib/context.ts24-68 docs/api/components/Route.md1-49

布局和嵌套组件

React Router 通过嵌套路由和专用组件支持 UI 组合。

来源： packages/react-router/lib/components.tsx657-659 packages/react-router/lib/hooks.tsx321-329

Outlet 组件

Outlet 组件用作子路由将被渲染的占位符。这允许父路由将导航、侧边栏等布局元素包装到子路由中。

Outlet 组件还可以接受 context 属性，它允许将数据从父路由传递到其子路由。这些数据可以在子组件中使用 useOutletContext hook 访问。

来源： packages/react-router/lib/components.tsx657-659 packages/react-router/lib/hooks.tsx321-329 packages/react-router/lib/hooks.tsx311-313

导航组件

React Router 提供了多种组件和钩子用于在路由之间进行导航。

来源： packages/react-router/lib/dom/lib.tsx605-747 packages/react-router/lib/components.tsx580-621 docs/api/components/Link.md1-179

链接组件

Link 组件是 React Router 中导航到路由的主要方式。它会渲染一个带有适当 href 的 <a> 标签，但会拦截点击事件，以进行客户端导航，而无需完全重新加载页面。

关键属性

• to：目标路径（字符串或包含 pathname、search、hash 的对象）
• replace：替换当前历史记录，而不是添加新记录
• state：要持久化到目标位置的状态
• preventScrollReset：在导航时阻止滚动位置重置
• relative：如何解析相对路径（"route" 或 "path"）
• reloadDocument：绕过客户端路由，使用常规浏览器导航
• prefetch：控制预取行为（框架模式）
• viewTransition：启用 View Transitions API 动画

来源： packages/react-router/lib/dom/lib.tsx605-747 docs/api/components/Link.md1-179

Navigate 组件

Navigate 组件是一种声明式的方式来改变路由。当它被渲染时，它会自动导航到指定的路由。

此组件对于组件内的重定向很有用

通常不应使用 Navigate 组件进行基于事件的导航（如按钮点击）。对于这些情况，请改用 useNavigate 钩子。

来源： packages/react-router/lib/components.tsx580-621

组件层次结构和上下文流

React Router 大量使用 React context 在组件之间共享路由状态。这个上下文系统是组件如何交互的骨干。

来源： packages/react-router/lib/context.ts87-203 packages/react-router/lib/components.tsx751-825

上下文系统

React Router 使用几个上下文提供程序来通过组件树传递数据

1. NavigationContext：提供 basename 和 navigator 对象
2. LocationContext：提供当前位置和导航类型
3. RouteContext：提供匹配的路由和用于渲染的 outlet
4. DataRouterContext：对于数据路由，提供 router 实例
5. DataRouterStateContext：对于数据路由，提供 router 状态

组件可以通过 useLocation、useNavigate 和 useParams 等钩子来访问这些上下文。

来源： packages/react-router/lib/context.ts87-203 packages/react-router/lib/hooks.tsx133-142

组件渲染流程

React Router 中的渲染流程通常遵循以下模式：

1. 路由组件（BrowserRouter、RouterProvider 等）设置上下文提供程序。
2. Routes 组件将其 Route 子项与当前 URL 进行匹配。
3. 匹配的 Route 渲染其 element 属性。
4. 父路由通过 Outlet 组件渲染其子路由。
5. 导航组件（如 Link）更新历史记录，从而触发重新渲染。

这个流程使得 React Router 能够采取声明式路由方法，其中 UI 是当前 URL 的函数。

来源： packages/react-router/lib/components.tsx859-864 packages/react-router/lib/hooks.tsx425-620

典型用法模式

以下是使用 React Router 核心组件的一些常见模式：

基本路由

嵌套路由与布局

数据路由 API

来源： packages/react-router/lib/components.tsx243-489 packages/react-router/__tests__/data-memory-router-test.tsx57-70 packages/react-router/__tests__/data-memory-router-test.tsx89-98

总结

React Router 的核心组件为构建 React 应用程序中的导航提供了一个灵活的系统

• Router Components（BrowserRouter、HashRouter 等）建立了路由基础。
• Route Definition Components（Routes、Route）定义了 URL 和 UI 之间的映射。
• Layout Components（Outlet）支持嵌套 UI 组合。
• Navigation Components（Link、Navigate）提供了改变路由的方式。

这些组件共同创建了一个强大的系统，用于 React 应用程序中的声明式路由。它们封装了处理 URL 更改、历史记录管理和基于当前位置的组件渲染的复杂性。

有关数据加载等更高级的功能，请参阅 Data APIs，有关服务器渲染功能，请参阅 Server-Side Rendering。