useNavigate

摘要

返回一个函数，允许您响应用户交互或效果，在浏览器中以编程方式进行导航。

在 action/loader 函数中，使用 redirect 通常比使用此 hook 更好。

返回的函数签名为 navigate(to, options?)/navigate(delta)，其中

to 可以是字符串路径、To 对象或数字 (delta)
options 包含用于修改导航的选项
- flushSync: 将 DOM 更新包装在 ReactDom.flushSync 中
- preventScrollReset: 导航后不滚动回页面顶部
- relative: "route" 或 "path"，用于控制相对路由逻辑
- replace: 替换 History 堆栈中的当前条目
- state: 可选的 history.state，与新的 Location 一起包含
- viewTransition: 为此导航启用 document.startViewTransition

import { useNavigate } from "react-router";

function SomeComponent() {
  let navigate = useNavigate();
  return (
    <button onClick={() => navigate(-1)}>
      Go Back
    </button>
  );
}

签名

function useNavigate(): NavigateFunction

用于编程导航的 navigate 函数

示例

导航到另一个路径

navigate("/some/route");
navigate("/some/route?search=param");

使用 `To` 对象进行导航

所有属性都是可选的。

navigate({
  pathname: "/some/route",
  search: "?search=param",
  hash: "#hash",
  state: { some: "state" },
});

如果使用 state，它将在下一个页面的 Location 对象上可用。通过 useLocation().state 访问它（参见 useLocation）。

在历史堆栈中前进或后退

// back
// often used to close modals
navigate(-1);

// forward
// often used in a multistep wizard workflows
navigate(1);

请谨慎使用 navigate(number)。如果您的应用程序可以加载到一个路由，该路由上有一个尝试前进/后退的按钮，那么可能没有可供前进或后退的 `History` 条目，或者它可能会导航到您不期望的地方（例如不同的域）。

只有在确定它们在 History 堆栈中确实有条目可导航时才使用此功能。

替换历史堆栈中的当前条目

这将从 History 堆栈中删除当前条目，并用新条目替换它，类似于服务器端重定向。

navigate("/some/route", { replace: true });

阻止滚动重置

要防止 <ScrollRestoration> 重置滚动位置，请使用 preventScrollReset 选项。

navigate("?some-tab=1", { preventScrollReset: true });

例如，如果页面中间有一个连接到搜索参数的标签页界面，而您不希望在点击标签页时滚动到顶部。

返回类型增强

在内部，当您处于声明式模式与数据/框架模式时，useNavigate 会使用不同的实现——主要区别在于后者能够返回一个在导航过程中不会改变标识的稳定引用。数据/框架模式下的实现还会返回一个在导航完成时解析的 Promise。这意味着 useNavigate 的返回类型是 void | Promise<void>。这是准确的，但由于返回值的联合类型，可能会导致一些红色波浪线。

如果您正在使用 typescript-eslint，您可能会看到来自 @typescript-eslint/no-floating-promises 的错误。
在框架/数据模式下，React.use(navigate()) 会显示一个误报的 'void | Promise<void>' 类型的参数不能赋给 'Usable<void>' 类型的参数 错误。

解决这些问题的最简单方法是根据您使用的路由器来增强类型。

// If using <BrowserRouter>
declare module "react-router" {
  interface NavigateFunction {
    (to: To, options?: NavigateOptions): void;
    (delta: number): void;
  }
}

// If using <RouterProvider> or Framework mode
declare module "react-router" {
  interface NavigateFunction {
    (to: To, options?: NavigateOptions): Promise<void>;
    (delta: number): Promise<void>;
  }
}