├── .gitattributes
├── .github
└── workflows
│ └── deploy.yml
├── .gitignore
├── LICENSE
├── README.md
├── docs
└── .vitepress
│ ├── config.mts
│ └── theme
│ ├── custom.css
│ └── index.mts
├── package.json
├── pnpm-lock.yaml
└── src
├── components
├── await.md
├── form.md
├── link-native.md
├── link.md
├── nav-link.md
├── navigate.md
├── outlet.md
├── route.md
├── routes.md
└── scroll-restoration.md
├── fetch
├── json.md
├── redirect-document.md
└── redirect.md
├── guides
├── api-development-strategy.md
├── contributing.md
├── data-libs.md
├── deferred.md
├── form-data.md
├── index-search-param.md
└── ssr.md
├── hooks
├── use-action-data.md
├── use-async-error.md
├── use-async-value.md
├── use-before-unload.md
├── use-blocker.md
├── use-fetcher.md
├── use-fetchers.md
├── use-form-action.md
├── use-href.md
├── use-in-router-context.md
├── use-link-click-handler.md
├── use-link-press-handler.md
├── use-loader-data.md
├── use-location.md
├── use-match.md
├── use-matches.md
├── use-navigate.md
├── use-navigation-type.md
├── use-navigation.md
├── use-outlet-context.md
├── use-outlet.md
├── use-params.md
├── use-prompt.md
├── use-resolved-path.md
├── use-revalidator.md
├── use-route-error.md
├── use-route-loader-data.md
├── use-routes.md
├── use-search-params-rn.md
├── use-search-params.md
├── use-submit.md
└── use-view-transition-state.md
├── index.md
├── public
├── favicon.ico
├── logo.svg
└── logo_dark.svg
├── route
├── action.md
├── error-element.md
├── hydrate-fallback-element.md
├── lazy.md
├── loader.md
├── route.md
└── should-revalidate.md
├── router-components
├── browser-router.md
├── hash-router.md
├── memory-router.md
├── native-router.md
├── router.md
└── static-router.md
├── routers
├── create-browser-router.md
├── create-hash-router.md
├── create-memory-router.md
├── create-static-handler.md
├── create-static-router.md
├── picking-a-router.md
├── router-provider.md
└── static-router-provider.md
├── start
├── concepts.md
├── faqs.md
├── overview.md
└── tutorial.md
├── upgrading
├── reach.md
├── v5.md
└── v6-data.md
└── utils
├── create-routes-from-children.md
├── create-routes-from-elements.md
├── create-search-params.md
├── defer.md
├── generate-path.md
├── is-route-error-response.md
├── location.md
├── match-path.md
├── match-routes.md
├── render-matches.md
└── resolve-path.md
/.gitattributes:
--------------------------------------------------------------------------------
1 | *.md linguist-language=TypeScript
2 |
--------------------------------------------------------------------------------
/.github/workflows/deploy.yml:
--------------------------------------------------------------------------------
1 | name: deploy
2 |
3 | on:
4 | push:
5 | branches:
6 | - main
7 |
8 | jobs:
9 | push-to-gh-pages:
10 | runs-on: ubuntu-latest
11 | steps:
12 | - name: Checkout
13 | uses: actions/checkout@v3
14 | with:
15 | persist-credentials: false
16 |
17 | - name: Install pnpm
18 | uses: pnpm/action-setup@v2
19 | with:
20 | version: 8
21 | run_install: false
22 |
23 | - name: use Node.js
24 | uses: actions/setup-node@v3
25 | with:
26 | node-version: '20.x'
27 |
28 | - name: Build
29 | env:
30 | NODE_OPTIONS: '--max_old_space_size=4096'
31 | run: |
32 | pnpm install
33 | pnpm run docs:build
34 |
35 | - name: Deploy
36 | uses: JamesIves/github-pages-deploy-action@v4.3.3
37 | with:
38 | ACCESS_TOKEN: ${{ secrets.DEPLOY_KEY }}
39 | BRANCH: gh-pages
40 | FOLDER: ./dist
41 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | dist/
2 | node_modules/
3 | docs/.vitepress/cache/
4 |
5 | .git
6 | .idea
7 | .vscode
8 | .DS_Store
9 |
10 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2023 baimingxuan
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 |
2 |
React Router6 中文文档（v6.21.1）
3 |
文档内容详细翻译自官方英文文档
4 |
7 |
9 |
10 | ### 开发
11 |
12 | ```sh
13 | # 克隆项目
14 | git clone https://github.com/baimingxuan/react-router6-doc.git
15 |
16 | # 安装依赖
17 | pnpm install
18 |
19 | # 开发
20 | pnpm run docs:dev
21 | ```
22 |
23 | 项目基于 [vitepress](https://github.com/vuejs/vitepress)
24 |
25 |
--------------------------------------------------------------------------------
/docs/.vitepress/theme/custom.css:
--------------------------------------------------------------------------------
1 | .logo {
2 | margin-right: 0 !important;
3 | }
--------------------------------------------------------------------------------
/docs/.vitepress/theme/index.mts:
--------------------------------------------------------------------------------
1 | import DefaultTheme from 'vitepress/theme'
2 | import './custom.css'
3 |
4 | export default DefaultTheme
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "react-router6-doc",
3 | "version": "1.0.0",
4 | "description": "react router v6.21.1 chinese document",
5 | "repository": "https://github.com/baimingxuan/react-router6-doc.git",
6 | "author": "baimingxuan",
7 | "license": "MIT License",
8 | "scripts": {
9 | "docs:dev": "vitepress dev docs --host",
10 | "docs:build": "vitepress build docs",
11 | "docs:preview": "vitepress preview docs"
12 | },
13 | "devDependencies": {
14 | "vitepress": "1.0.0-rc.24"
15 | }
16 | }
--------------------------------------------------------------------------------
/src/components/await.md:
--------------------------------------------------------------------------------
1 | # ``
2 |
3 | 用于呈现具有自动错误处理的功能[延迟值](../utils/defer)。请务必查看[延迟数据指南](../guides/deferred)，因为有一些 API 与此组件配合使用。
4 |
5 | ```jsx
6 | import { Await, useLoaderData } from "react-router-dom";
7 |
8 | function Book() {
9 | const { book, reviews } = useLoaderData();
10 | return (
11 |
12 |
{book.title}
13 |
{book.description}
14 |
}>
15 |
Could not load reviews 😬{/* ... */}
;
72 | }
73 | ```
74 |
75 | ## `errorElement`
76 |
77 | 当Promise被拒绝时，错误元素会渲染，而不是子元素。您可以通过[`useAsyncError`](../hooks/use-async-error)访问错误。
78 |
79 | 如果Promise被拒绝，您可以提供一个可选的 `errorElement` ，通过 `useAsyncError` 钩子在上下文用户界面中处理该错误。
80 |
81 | ```jsx
82 | }
85 | >
86 |
87 | ;
88 |
89 | function ReviewsError() {
90 | const error = useAsyncError();
91 | return {error.message}
;
92 | }
93 | ```
94 |
95 | 如果不提供 errorElement，被拒绝的值将上升到最近的路由级[`errorElement`](../route/error-element)，并可通过[`useRouteError`](../hooks/use-route-error)钩子访问。
96 |
97 | ## `resolve`
98 |
99 | 获取从[延迟](../utils/defer) [加载器](../route/loader)返回的 `promise`值，并进行解析和渲染。
100 |
101 | ```jsx
102 | import {
103 | defer,
104 | Route,
105 | useLoaderData,
106 | Await,
107 | } from "react-router-dom";
108 |
109 | // given this route
110 | {
112 | let book = await getBook();
113 | let reviews = getReviews(); // not awaited
114 | return defer({
115 | book,
116 | reviews, // this is a promise
117 | });
118 | }}
119 | element={}
120 | />;
121 |
122 | function Book() {
123 | const {
124 | book,
125 | reviews, // this is the same promise
126 | } = useLoaderData();
127 | return (
128 |
129 |
{book.title}
130 |
{book.description}
131 |
}>
132 |
136 |
137 |
138 |
139 |
17 | {/* ... */}
18 |
19 |
20 | );
21 | }
22 | ```
23 |
24 | ## `getKey`
25 |
26 | 可选属性，用于定义 React Router 恢复滚动位置时应使用的键。
27 |
28 | ```jsx
29 | {
31 | // default behavior
32 | return location.key;
33 | }}
34 | />
35 | ```
36 |
37 | 默认情况下，它使用 `location.key` ，在没有客户端路由的情况下模拟浏览器的默认行为。用户可以在堆栈中多次导航到相同的 URL，每个条目都有自己的滚动位置来还原。
38 |
39 | 有些应用可能希望覆盖这一行为，并根据其他内容恢复位置。例如，一个社交应用程序有四个主要页面：
40 |
41 | - "/home"
42 | - "/messages"
43 | - "/notifications"
44 | - "/search"
45 |
46 | 如果用户从"/home "开始，向下滚动一点，点击导航菜单中的 "信息"，然后点击导航菜单中的 "主页"（而不是返回按钮！），历史堆栈中就会出现三个条目：
47 |
48 | ```js
49 | 1. /home
50 | 2. /messages
51 | 3. /home
52 | ```
53 |
54 | 默认情况下，React Router（和浏览器）会为 `1` 和 `3` 存储两个不同的滚动位置，即使它们的 URL 相同。这意味着当用户从 `2` → `3` 浏览时，滚动位置会移到顶部，而不是恢复到 `1` 中的位置。
55 |
56 | 这里一个可靠的产品决策是，无论用户如何到达（返回按钮或新链接点击），都要保持他们在主页上的滚动位置。为此，您需要使用 `location.pathname` 作为关键字。
57 |
58 | ```jsx
59 | {
61 | return location.pathname;
62 | }}
63 | />
64 | ```
65 |
66 | 或者，您可能只想对某些路径使用路径名，而对其他路径使用正常行为：
67 |
68 | ```jsx
69 | {
71 | const paths = ["/home", "/notifications"];
72 | return paths.includes(location.pathname)
73 | ? // home and notifications restore by pathname
74 | location.pathname
75 | : // everything else by location like the browser
76 | location.key;
77 | }}
78 | />
79 | ```
80 |
81 | ## 防止滚动重置
82 |
83 | 当导航创建新的滚动键时，滚动位置会重置为页面顶部。您可以防止链接和表单出现 "滚动到顶部 "行为：
84 |
85 | ```jsx
86 |
87 |
88 | ```
89 |
90 | 另请参阅：[``](../components/link#preventscrollreset),[`
88 |
89 | );
90 | }
91 |
92 | function SomeView() {
93 | // instead of accessing with useAsyncValue
94 | // const someData = useAsyncValue();
95 | // `useQuery` as usual
96 | const { data } = useQuery("someKey");
97 | // ...
98 | }
99 | ```
100 |
101 | ## 重合部分
102 |
103 | 像 `useQuery` 这样的钩子经常返回 pending 和 error 状态，您可以使用它们来拆分您的 UI。使用 React Router，您可以将所有这些分支逻辑放在[`errorElement`](../route/error-element)、[`useNavigation`](../hooks/use-navigation)和[`Await`](../components/await)中，避免在正常路径组件中处理分支逻辑。
104 |
105 | ## 结论
106 |
107 | 有了所有这些 API 的协同工作，您现在就可以使用来自 React Router 的[`useNavigation`](../hooks/use-navigation)来构建待处理状态、优化的用户界面等。使用 React Router 为数据加载、突变和导航状态计时，然后使用 React Query 等库实际实现加载、失效、存储和缓存。
--------------------------------------------------------------------------------
/src/guides/deferred.md:
--------------------------------------------------------------------------------
1 | # 延迟数据指南
2 |
3 | ## 问题
4 |
5 | 想象一下这样一种场景：您的某个路径`loader`需要检索一些数据，而由于某种原因，检索速度相当慢。例如，您要向用户显示一个包裹的位置，该包裹正被送往用户家中：
6 |
7 | ```jsx
8 | import { json, useLoaderData } from "react-router-dom";
9 | import { getPackageLocation } from "./api/packages";
10 |
11 | async function loader({ params }) {
12 | const packageLocation = await getPackageLocation(
13 | params.packageId
14 | );
15 |
16 | return json({ packageLocation });
17 | }
18 |
19 | function PackageRoute() {
20 | const data = useLoaderData();
21 | const { packageLocation } = data;
22 |
23 | return (
24 |
25 | Let's locate your package
26 |
27 | Your package is at {packageLocation.latitude} lat
28 | and {packageLocation.longitude} long.
29 |
30 |
31 | );
32 | }
33 | ```
34 |
35 | 我们假设 `getPackageLocation` 速度较慢。这将导致初始页面加载时间和路径转换时间与最慢的数据一样长。有几种方法可以优化这种情况并改善用户体验：
36 |
37 | - 让缓慢的事情加速（😅）。
38 | - 使用 `Promise.all` 实现数据加载的并行化（在我们的示例中没有什么需要并行化的，但在其他情况下可能会有点帮助）。
39 | - 添加全局过渡旋转器（对用户体验有一定帮助）。
40 | - 添加本地化的骨架用户界面（对用户体验有一定帮助）。
41 |
42 | 如果这些方法效果不佳，那么您可能不得不将慢速数据从 `loader` 移到组件获取中（并在加载时显示骨架回退 UI）。在这种情况下，您需要在挂载时渲染后备 UI，然后启动数据获取。从 DX 的角度来看，这其实并不可怕，这要归功于[`useFetcher`](../hooks/use-fetcher)。从用户体验的角度来看，这改善了客户端转换和初始页面加载的加载体验。因此，这似乎确实解决了问题。
43 |
44 | 但由于以下两个原因，在大多数情况下（尤其是在对路由组件进行代码拆分的情况下），它仍然不是最佳选择：
45 |
46 | 1. 客户端获取将数据请求置于瀑布式流程中：文档 -> JavaScript -> 懒加载路由 -> 数据获取
47 | 2. 您的代码无法在组件获取和路由获取之间轻松切换（稍后将详细介绍）。
48 |
49 | ## 解决方案
50 |
51 | React Router 使用 [`defer`响应](../utils/defer) 实用程序和 [``](../components/await) 组件/[ `useAsyncValue`](../hooks/use-async-value) 钩子，并利用 React 18 的 Suspense 来获取数据。通过使用这些 API，您可以解决这两个问题：
52 |
53 | 1. 您的数据不再是瀑布式的：文档 -> JavaScript -> 懒加载路径和数据（并行）。
54 | 2. 您的代码可以在渲染回退和等待数据之间轻松切换
55 |
56 | 让我们深入了解一下如何做到这一点。
57 |
58 | ### 使用`defer`
59 |
60 | 首先，为您的慢速数据请求添加 `` ，在这种情况下，您更希望呈现一个回调 UI。让我们在上面的示例中这样做：
61 |
62 | ```jsx
63 | import {
64 | Await,
65 | defer,
66 | useLoaderData,
67 | } from "react-router-dom";
68 | import { getPackageLocation } from "./api/packages";
69 |
70 | async function loader({ params }) {
71 | const packageLocationPromise = getPackageLocation(
72 | params.packageId
73 | );
74 |
75 | return defer({
76 | packageLocation: packageLocationPromise,
77 | });
78 | }
79 |
80 | export default function PackageRoute() {
81 | const data = useLoaderData();
82 |
83 | return (
84 |
85 | Let's locate your package
86 | Loading package location...}
88 | >
89 | Error loading package location!
93 | }
94 | >
95 | {(packageLocation) => (
96 |
97 | Your package is at {packageLocation.latitude}{" "}
98 | lat and {packageLocation.longitude} long.
99 |
100 | )}
101 |
102 |
103 |
104 | );
105 | }
106 | ```
107 |
108 | 或者，也可以使用 `useAsyncValue` 钩子：
109 |
110 | 如果你不喜欢使用 render 属性，你可以使用一个 Hook，但你必须把代码拆分成另一个组件：
111 |
112 | ```jsx
113 | export default function PackageRoute() {
114 | const data = useLoaderData();
115 |
116 | return (
117 |
118 | Let's locate your package
119 | Loading package location...}
121 | >
122 | Error loading package location!
126 | }
127 | >
128 |
129 |
130 |
131 |
132 | );
133 | }
134 |
135 | function PackageLocation() {
136 | const packageLocation = useAsyncValue();
137 | return (
138 |
139 | Your package is at {packageLocation.latitude} lat and{" "}
140 | {packageLocation.longitude} long.
141 |
142 | );
143 | }
144 | ```
145 |
146 | ## 评估解决方案
147 |
148 | 因此，我们不会在触发获取请求前等待组件，而是在用户开始转换到新路由时，立即启动对慢速数据的请求。这可以大大加快较慢网络的用户体验。
149 |
150 | 此外，React Router 为此提供的 API 非常人性化。您可以根据是否包含 `await` 关键字，在是否延迟之间进行切换：
151 |
152 | ```jsx
153 | return defer({
154 | // not deferred:
155 | packageLocation: await packageLocationPromise,
156 | // deferred:
157 | packageLocation: packageLocationPromise,
158 | });
159 | ```
160 |
161 | 因此，您可以进行 A/B 延迟测试，甚至可以根据用户或请求的数据来决定是否延迟：
162 |
163 | ```jsx
164 | async function loader({ request, params }) {
165 | const packageLocationPromise = getPackageLocation(
166 | params.packageId
167 | );
168 | const shouldDefer = shouldDeferPackageLocation(
169 | request,
170 | params.packageId
171 | );
172 |
173 | return defer({
174 | packageLocation: shouldDefer
175 | ? packageLocationPromise
176 | : await packageLocationPromise,
177 | });
178 | }
179 | ```
180 |
181 | `shouldDeferPackageLocation` 可以用来检查提出请求的用户、软件包位置数据是否在缓存中、A/B 测试的状态或其他任何你想要的信息。这真是太贴心了 🍭
182 |
183 | ## 常问问题
184 |
185 | ### 为什么不默认推迟一切？
186 |
187 | eact Router defer API 是 React Router 提供的另一个工具，它为您提供了一种在权衡之间做出选择的好方法。你想让页面渲染得更快吗？那就延迟吧。你想要更低的 CLS（内容布局偏移）？不要延迟。你想要更快的渲染速度，但也想要更低的 CLS？那就只延迟那些慢且不重要的内容。
188 |
189 | 这都是权衡的结果，而 API 设计的精妙之处在于，它非常适合你进行简单的实验，看看哪种权衡方式能为你的真实世界关键指标带来更好的结果。
190 |
191 | ### ``回退何时渲染？
192 |
193 | `` 组件只会在初始呈现 `` 组件时，在 `` 边界上抛出`promise`，且`promise`未确定。如果属性发生变化，它不会重新渲染回调。实际上，这意味着当用户提交表单并重新验证`loader`数据时，不会呈现回调。当用户使用不同的参数导航到相同的路径时（在上述示例中，如果用户从左侧的套餐列表中选择在右侧找到自己的位置），就会呈现回调。
194 |
195 | 一开始，我们可能会觉得这与直觉相悖，但请别急，我们已经仔细考虑过这个问题，而且这种工作方式非常重要。让我们想象一下没有延迟 API 的世界。在这种情况下，您可能需要为表单提交/重新验证实现优化用户界面。
196 |
197 | 当您决定尝试 `defer` 的权衡时，我们不希望您必须更改或移除这些优化，因为我们希望您能在推迟和不推迟某些数据之间轻松切换。因此，我们确保您现有的乐观状态以同样的方式运行。如果我们不这样做，您可能会体验到我们所说的 "Popcorn UI"，即提交数据会触发回调加载状态，而不是您辛苦开发的优化的用户界面。
198 |
199 | 因此，请记住这一点：**延迟 100% 只涉及路由及其参数的初始加载**。
200 |
201 | ### 为什么加载器返回的响应对象不再起作用了？
202 |
203 | 当您使用 `defer` 时，您是在告诉 React Router 立即加载页面，而不使用延迟数据。在返回 `Response` 对象之前，页面已经加载完毕，因此响应的自动处理方式与使用 `return fetch(url)` 时不同。
204 |
205 | 因此，您需要处理自己的 `Response` 进程，并使用数据而不是 `Response` 实例来解决您的延迟 Promise 问题。
206 |
207 | ```jsx
208 | async function loader({ request, params }) {
209 | return defer({
210 | // Broken! Resolves with a Response
211 | // broken: fetch(url),
212 |
213 | // Fixed! Resolves with the response data
214 | data: fetch(url).then((res) => res.json()),
215 | });
216 | }
217 | ```
218 |
219 | 或者考虑一下我们的延迟数据会返回重定向 `Response` 的情况。您可以检测重定向并将状态代码和位置作为数据发送回来，然后您可以通过 `useEffect` 和 `useNavigate` 在组件中执行客户端重定向。
220 |
221 | ```jsx
222 | async function loader({ request, params }) {
223 | let data = fetch(url).then((res) => {
224 | if (res.status == 301) {
225 | return {
226 | isRedirect: true,
227 | status: res.status,
228 | location: res.headers.get("Location"),
229 | };
230 | }
231 | return res.json();
232 | });
233 |
234 | return defer({ data });
235 | }
236 | ```
--------------------------------------------------------------------------------
/src/guides/form-data.md:
--------------------------------------------------------------------------------
1 | # 使用 FormData
2 |
3 | > NOTE
4 | >
5 | > TODO：本文档为存根
6 |
7 | 常见的技巧是使用[`Object.fromEntries`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/fromEntries)将整个 formData 转换为对象：
8 |
9 | ```jsx
10 | const data = Object.fromEntries(await request.formData());
11 | data.songTitle;
12 | data.lyrics;
13 | ```
14 |
15 |
--------------------------------------------------------------------------------
/src/guides/index-search-param.md:
--------------------------------------------------------------------------------
1 | # 索引查询参数
2 |
3 | 在提交表单时，您可能会发现应用程序的 URL 中出现一个乱码 `?index` 。
4 |
5 | 由于存在嵌套路由，路由层次结构中的多个路由都能与 URL 匹配。与导航不同的是，导航会调用所有匹配的路由加载器来构建用户界面，而提交表单时*只会调用一个操作*。
6 |
7 | 由于索引路由与其父路由共享相同的 URL，因此 `?index` 参数可帮助您区分两者。
8 |
9 | 例如，请看下面的路由和表单：
10 |
11 | ```jsx
12 | createBrowserRouter([
13 | {
14 | path: "/projects",
15 | element: ,
16 | action: ProjectsLayout.action,
17 | children: [
18 | {
19 | index: true,
20 | element: ,
21 | action: ProjectsPage.action,
22 | },
23 | ],
24 | },
25 | ]);
26 |
27 | ;
28 | ;
29 | ```
30 |
31 | `?index` 参数将提交到索引路由，不带索引参数的操作将提交到父路由。
32 |
33 | 当 `;
38 | }
39 | ```
40 |
41 | 如果您将代码移至 `ProjectsLayout` 路由，它将转而发布到 `/projects` 。
42 |
43 | 这适用于 `