React / 系统课时
编程式导航
编程式导航
本课解决“操作完成后如何由代码控制跳转”的问题。你将用 React Router 的 useNavigate 在登录、创建、编辑和删除后跳转到目标页面,并掌握替换历史记录、返回上一页和携带临时状态的正确用法。
学习目标
- 使用
useNavigate完成跳转、替换和返回 - 根据操作结果决定导航时机与目标地址
- 避免重复提交、错误返回和状态丢失
编程式导航解决什么问题
声明式导航适合用户主动点击链接,编程式导航则适合“业务动作完成后自动跳转”。常见场景包括登录成功进入工作台、创建成功进入详情页、编辑完成返回列表,以及删除成功后离开已经不存在的详情页。
useNavigate 返回一个导航函数。传入路径时会进入目标路由,传入数字时会在浏览器历史记录中前进或后退。
片段示例:以下调用需位于 BrowserRouter 下的组件中,并已通过 useNavigate 获取 navigate。
const navigate = useNavigate();
navigate("/dashboard");
navigate("/login", { replace: true });
navigate(-1);这些调用的核心区别是:普通跳转会新增一条历史记录,replace: true 会替换当前记录,负数参数则按历史记录返回。

完整示例:创建成功后进入详情页
下面的示例包含列表页、创建页和详情页。提交表单后先模拟创建数据,再跳转到新记录的详情页,并通过 state 传递一次性提示信息。
import React, { FormEvent, useState } from "react";
import {
BrowserRouter,
Link,
Route,
Routes,
useLocation,
useNavigate,
useParams,
} from "react-router-dom";
import { createRoot } from "react-dom/client";
function ProductList() {
return (
<main>
<h2>商品列表</h2>
<Link to="/products/new">创建商品</Link>
</main>
);
}
function ProductCreate() {
const navigate = useNavigate();
const [name, setName] = useState("");
const [submitting, setSubmitting] = useState(false);
async function handleSubmit(event: FormEvent<HTMLFormElement>) {
event.preventDefault();
if (!name.trim() || submitting) return;
// 请求期间锁定按钮,避免重复创建和重复导航。
setSubmitting(true);
// 模拟接口返回新建记录的 ID。
await new Promise((resolve) => setTimeout(resolve, 300));
const productId = "p-1001";
// 替换创建页记录,后退时不会再次回到已提交表单。
navigate(`/products/${productId}`, {
replace: true,
state: { message: `商品“${name.trim()}”创建成功` },
});
}
return (
<main>
<h2>创建商品</h2>
<form onSubmit={handleSubmit}>
<input
value={name}
onChange={(event) => setName(event.target.value)}
placeholder="请输入商品名称"
/>
<button type="submit" disabled={submitting}>
{submitting ? "提交中..." : "创建"}
</button>
</form>
</main>
);
}
function ProductDetail() {
const { productId } = useParams();
const location = useLocation();
const navigate = useNavigate();
const message = (location.state as { message?: string } | null)?.message;
return (
<main>
<h2>商品详情</h2>
{message && <p>{message}</p>}
<p>商品 ID:{productId}</p>
<button onClick={() => navigate("/products")}>返回列表</button>
</main>
);
}
function App() {
return (
<BrowserRouter>
<Routes>
<Route path="/products" element={<ProductList />} />
<Route path="/products/new" element={<ProductCreate />} />
<Route path="/products/:productId" element={<ProductDetail />} />
<Route path="*" element={<ProductList />} />
</Routes>
</BrowserRouter>
);
}
createRoot(document.getElementById("root")!).render(<App />);预期结果
1. 打开 /products 后可进入创建页。
2. 输入商品名称并提交,按钮显示“提交中...”。
3. 创建完成后地址变为 /products/p-1001。
4. 详情页显示创建成功提示和商品 ID。
5. 因为使用 replace,浏览器后退不会再次回到创建表单。实际项目中应把模拟等待替换为真实请求,并且只在接口明确成功后导航。接口失败时应保留当前页面,恢复按钮状态并展示错误信息。
跳转、替换与返回的选择
普通跳转适合用户可能需要返回来源页的场景,例如从列表进入详情。replace: true 适合登录页、创建成功页等不应再次进入的中间状态,否则用户后退时可能看到已提交表单或再次触发流程。
navigate(-1) 适合确实存在可靠来源页的情况。若页面可能被直接打开,历史记录中未必有站内页面,此时应提供明确的兜底路径,例如返回列表而不是盲目后退。
下面的组件需要渲染在路由上下文中。初始文档加载时 location.key 通常为 default,此时直接进入明确的兜底页,不依赖不确定的浏览器来源。
import { useLocation, useNavigate } from "react-router-dom";
export function BackButton() {
const location = useLocation();
const navigate = useNavigate();
function handleBack() {
if (location.key !== "default") {
navigate(-1);
return;
}
navigate("/products", { replace: true });
}
return <button onClick={handleBack}>返回</button>;
}预期结果
站内导航进入当前页时返回上一条记录;直接加载当前地址时进入 /products。关键边界与常见错误
不要在组件渲染阶段直接调用 navigate,否则可能产生重复导航。需要根据状态自动跳转时,应放在事件处理函数或 useEffect 中,并保证依赖条件稳定。
location.state 只适合一次性页面提示,不适合保存必须持久化的数据。刷新页面后这类状态可能丢失,详情内容仍应根据 URL 参数重新请求。
提交按钮应在请求期间禁用,避免用户连续点击造成重复创建和多次导航。删除详情页后通常应使用替换导航进入列表,防止用户后退到已经失效的记录。