从 v6 升级

如果您启用了所有未来标志，则 v7 升级没有重大更改。这些标志允许您一次更改一个更改来更新您的应用程序。我们强烈建议您在每个步骤之后提交并发布它，而不是一次性完成所有操作。

更新到最新 v6.x

首先更新到最新 v6.x 的次要版本，以获取最新的未来标志和控制台警告。

👉 更新到最新 v6

npm install react-router-dom@6

v7_relativeSplatPath

背景

更改了多段 splat 路径（如 dashboard/*（与仅 * 相比））的相对路径匹配和链接。查看更改日志以获取更多信息。

👉 启用标志

启用标志取决于路由器的类型

<BrowserRouter
  future={{
    v7_relativeSplatPath: true,
  }}
/>

createBrowserRouter(routes, {
  future: {
    v7_relativeSplatPath: true,
  },
});

更新您的代码

如果您有任何带有路径和 splat 的路由，例如 <Route path="dashboard/*">，这些路由在其下方具有相对链接，例如 <Link to="relative"> 或 <Link to="../relative">，您需要更新您的代码。

👉 将 <Route> 分为两个

将任何多段 splat <Route> 分为一个具有路径的父路由和一个具有 splat 的子路由

<Routes>
  <Route path="/" element={<Home />} />
-  <Route path="dashboard/*" element={<Dashboard />} />
+  <Route path="dashboard">
+    <Route path="*" element={<Dashboard />} />
+  </Route>
</Routes>

// or
createBrowserRouter([
  { path: "/", element: <Home /> },
  {
-    path: "dashboard/*",
-    element: <Dashboard />,
+    path: "dashboard",
+    children: [{ path: "*", element: <Dashboard /> }],
  },
]);

👉 更新相对链接

更新该路由树中的任何 <Link> 元素以包含额外的 .. 相对段以继续链接到相同的位置

function Dashboard() {
  return (
    <div>
      <h2>Dashboard</h2>
      <nav>
-        <Link to="/">Dashboard Home</Link>
-        <Link to="team">Team</Link>
-        <Link to="projects">Projects</Link>
+        <Link to="../">Dashboard Home</Link>
+        <Link to="../team">Team</Link>
+        <Link to="../projects">Projects</Link>
      </nav>

      <Routes>
        <Route path="/" element={<DashboardHome />} />
        <Route path="team" element={<DashboardTeam />} />
        <Route
          path="projects"
          element={<DashboardProjects />}
        />
      </Routes>
    </div>
  );
}

v7_startTransition

背景

这使用 React.useTransition 而不是 React.useState 来更新路由器状态。查看更改日志以获取更多信息。

👉 启用标志

<BrowserRouter
  future={{
    v7_startTransition: true,
  }}
/>

// or
<RouterProvider
  future={{
    v7_startTransition: true,
  }}
/>

👉 更新您的代码

除非您在组件内部使用 React.lazy，否则您无需更新任何内容。

在组件内部使用 React.lazy 与 React.useTransition（或在组件内部创建 promise 的其他代码）不兼容。将 React.lazy 移动到模块范围并停止在组件内部创建 promise。这不是 React Router 的限制，而是 React 的不正确用法。

v7_fetcherPersist

如果您没有使用 <RouterProvider>，您可以跳过此步骤

背景

fetcher 生命周期现在基于它何时返回空闲状态，而不是何时其所有者组件卸载：查看更改日志以获取更多信息。

启用标志

createBrowserRouter(routes, {
  future: {
    v7_fetcherPersist: true,
  },
});

更新您的代码

它不太可能影响您的应用程序。您可能需要检查 useFetchers 的任何用法，因为它们可能比以前持续更长时间。根据您正在执行的操作，您可能比以前渲染更长时间。

v7_normalizeFormMethod

如果您没有使用 <RouterProvider>，您可以跳过此步骤

这将 formMethod 字段规范化为大写 HTTP 方法，以与 fetch() 行为保持一致。查看更改日志以获取更多信息。

👉 启用标志

createBrowserRouter(routes, {
  future: {
    v7_normalizeFormMethod: true,
  },
});

更新您的代码

如果您的任何代码正在检查小写 HTTP 方法，则需要将其更新为检查大写 HTTP 方法（或在其上调用 toLowerCase()）。

👉 将 formMethod 与大写进行比较

-useNavigation().formMethod === "post"
-useFetcher().formMethod === "get";
+useNavigation().formMethod === "POST"
+useFetcher().formMethod === "GET";

v7_partialHydration

如果您没有使用 <RouterProvider>，您可以跳过此步骤

这允许 SSR 框架仅提供部分水合数据。您不太需要担心这一点，只需打开标志即可。查看更改日志以获取更多信息。

👉 启用标志

createBrowserRouter(routes, {
  future: {
    v7_partialHydration: true,
  },
});

更新您的代码

使用部分水合，您需要提供一个 HydrateFallback 组件以在初始水合期间呈现。此外，如果您之前使用过 fallbackElement，则需要将其删除，因为它现在已弃用。在大多数情况下，您希望将 fallbackElement 重用为 HydrateFallback。

👉 将 fallbackElement 替换为 HydrateFallback

const router = createBrowserRouter(
  [
    {
      path: "/",
      Component: Layout,
+      HydrateFallback: Fallback,
      // or
+      hydrateFallbackElement: <Fallback />,
      children: [],
    },
  ],
);


<RouterProvider
  router={router}
-  fallbackElement={<Fallback />}
/>

v7_skipActionErrorRevalidation

如果您没有使用 createBrowserRouter，您可以跳过此步骤

启用此标志后，加载程序在操作抛出/返回状态代码为 4xx/5xx 的 Response 后将不再默认重新验证。您可以通过 shouldRevalidate 和 actionStatus 参数选择在此类情况下重新验证。

👉 启用标志

createBrowserRouter(routes, {
  future: {
    v7_skipActionErrorRevalidation: true,
  },
});

更新您的代码

在大多数情况下，您可能不必更改应用程序代码。通常，如果操作出错，则不太可能发生数据突变并需要重新验证。如果您的任何代码确实在操作错误情况下突变了数据，您有两个选择

👉 选项 1：更改 action 以避免在错误情况下发生突变

// Before
async function action() {
  await mutateSomeData();
  if (detectError()) {
    throw new Response(error, { status: 400 });
  }
  await mutateOtherData();
  // ...
}

// After
async function action() {
  if (detectError()) {
    throw new Response(error, { status: 400 });
  }
  // All data is now mutated after validations
  await mutateSomeData();
  await mutateOtherData();
  // ...
}

👉 选项 2：通过 shouldRevalidate 和 actionStatus 选择重新验证

async function action() {
  await mutateSomeData();
  if (detectError()) {
    throw new Response(error, { status: 400 });
  }
  await mutateOtherData();
}

async function loader() { ... }

function shouldRevalidate({ actionStatus, defaultShouldRevalidate }) {
  if (actionStatus != null && actionStatus >= 400) {
    // Revalidate this loader when actions return a 4xx/5xx status
    return true;
  }
  return defaultShouldRevalidate;
}

弃用

json 和 defer 方法已弃用，取而代之的是返回原始对象。

async function loader() {
- return json({ data });
+ return { data };

如果您使用 json 将数据序列化为 JSON，则可以使用本机 Response.json() 方法代替。

升级到 v7

现在您的应用程序已更新，您可以（理论上！）毫无问题地更新到 v7。

👉 安装 v7

npm install react-router-dom@latest

👉 将 react-router-dom 替换为 react-router

在 v7 中，我们不再需要 "react-router-dom"，因为软件包已简化。您可以从 "react-router" 中导入所有内容

npm uninstall react-router-dom
npm install react-router@latest

请注意，您只需要在 package.json 中使用 "react-router"。

👉 更新导入

现在您应该更新您的导入以使用 react-router

-import { useLocation } from "react-router-dom";
+import { useLocation } from "react-router";

您可以使用此命令代替手动更新导入。但是，请确保您的 git 工作树是干净的，以便在它无法按预期工作时进行回退。

find ./path/to/src \( -name "*.tsx" -o -name "*.ts" -o -name "*.js" -o -name "*.jsx" \) -type f -exec sed -i '' 's|from "react-router-dom"|from "react-router"|g' {} +

如果您安装了 GNU sed（大多数 Linux 发行版），请改用此命令

find ./path/to/src \( -name "*.tsx" -o -name "*.ts" -o -name "*.js" -o -name "*.jsx" \) -type f -exec sed -i 's|from "react-router-dom"|from "react-router"|g' {} +

👉 更新特定于 DOM 的导入

RouterProvider 和 HydratedRouter 来自深度导入，因为它们依赖于 "react-dom"

-import { RouterProvider } from "react-router-dom";
+import { RouterProvider } from "react-router/dom";

请注意，对于非 DOM 上下文（例如 Jest 测试），您应该使用顶级导入

-import { RouterProvider } from "react-router-dom";
+import { RouterProvider } from "react-router";

恭喜，您现在已使用 v7！