React / 系统课时
路由参数与查询条件
路由参数与查询条件
本课构建一个可运行的商品列表页:分类放在路径参数中,页码、状态和关键词放在查询字符串中,并让界面操作持续更新 URL,从而支持刷新恢复、复制链接和浏览器前进后退。
学习目标
- 使用
useParams读取动态路径参数 - 使用
useSearchParams读取和更新查询字符串 - 让分页、筛选与搜索状态以 URL 为单一事实来源
参数应该放在哪里
路径参数用于标识页面主体,例如 /products/frontend 中的 frontend;查询参数用于描述同一页面的查看方式,例如 ?page=2&status=online&q=React。
判断标准很简单:改变参数后若进入了另一类资源,优先使用路径参数;若仍是同一资源列表,只改变排序、筛选、分页或搜索条件,优先使用查询参数。

完整实现
下面的示例可直接替换 Vite React TypeScript 项目的 src/main.tsx。它使用内存数据模拟列表,不依赖后端接口。
import { StrictMode, useEffect, useMemo, useState, type FormEvent } from "react";
import { createRoot } from "react-dom/client";
import {
BrowserRouter,
Navigate,
Route,
Routes,
useNavigate,
useParams,
useSearchParams,
} from "react-router-dom";
type Status = "online" | "offline";
type Category = "frontend" | "backend";
const products = Array.from({ length: 24 }, (_, index) => {
const category: Category = index % 2 === 0 ? "frontend" : "backend";
return {
id: index + 1,
name: `${category === "frontend" ? "React" : "Node"} 商品 ${index + 1}`,
category,
status: (index % 3 === 0 ? "offline" : "online") as Status,
};
});
function ProductList() {
const { category = "frontend" } = useParams<{ category: Category }>();
const [searchParams, setSearchParams] = useSearchParams();
const navigate = useNavigate();
const rawPage = Number(searchParams.get("page") ?? "1");
const page = Number.isInteger(rawPage) && rawPage > 0 ? rawPage : 1;
const statusValue = searchParams.get("status");
const status: Status | "all" =
statusValue === "online" || statusValue === "offline" ? statusValue : "all";
const keyword = searchParams.get("q")?.trim() ?? "";
const [draft, setDraft] = useState(keyword);
// 浏览器前进、后退时,让输入框跟随 URL 恢复
useEffect(() => {
setDraft(keyword);
}, [keyword]);
function updateQuery(changes: Record<string, string | null>) {
const next = new URLSearchParams(searchParams);
Object.entries(changes).forEach(([key, value]) => {
value ? next.set(key, value) : next.delete(key);
});
setSearchParams(next);
}
const filtered = useMemo(
() =>
products.filter(
(item) =>
item.category === category &&
(status === "all" || item.status === status) &&
item.name.toLowerCase().includes(keyword.toLowerCase()),
),
[category, status, keyword],
);
const pageSize = 4;
const totalPages = Math.max(1, Math.ceil(filtered.length / pageSize));
const safePage = Math.min(page, totalPages);
const visible = filtered.slice((safePage - 1) * pageSize, safePage * pageSize);
function submitSearch(event: FormEvent) {
event.preventDefault();
// 搜索条件改变时回到第一页,避免停留在不存在的页码
updateQuery({ q: draft.trim() || null, page: "1" });
}
function changeCategory(nextCategory: Category) {
const query = searchParams.toString();
navigate(`/products/${nextCategory}${query ? `?${query}` : ""}`);
}
return (
<main style={{ maxWidth: 720, margin: "40px auto", fontFamily: "sans-serif" }}>
<h1>商品列表</h1>
<p>当前分类:{category}</p>
<button onClick={() => changeCategory("frontend")}>前端</button>
<button onClick={() => changeCategory("backend")}>后端</button>
<select
value={status}
onChange={(event) =>
updateQuery({ status: event.target.value === "all" ? null : event.target.value, page: "1" })
}
>
<option value="all">全部状态</option>
<option value="online">已上架</option>
<option value="offline">已下架</option>
</select>
<form onSubmit={submitSearch}>
<input
value={draft}
onChange={(event) => setDraft(event.target.value)}
placeholder="搜索商品"
/>
<button type="submit">搜索</button>
</form>
<ul>
{visible.map((item) => (
<li key={item.id}>
{item.name} - {item.status}
</li>
))}
</ul>
<button
disabled={safePage === 1}
onClick={() => updateQuery({ page: String(safePage - 1) })}
>
上一页
</button>
<span> 第 {safePage} / {totalPages} 页 </span>
<button
disabled={safePage === totalPages}
onClick={() => updateQuery({ page: String(safePage + 1) })}
>
下一页
</button>
</main>
);
}
function App() {
return (
<BrowserRouter>
<Routes>
<Route path="/" element={<Navigate to="/products/frontend" replace />} />
<Route path="/products/:category" element={<ProductList />} />
</Routes>
</BrowserRouter>
);
}
createRoot(document.getElementById("root")!).render(
<StrictMode>
<App />
</StrictMode>,
);预期结果
访问 /products/frontend?page=1&status=online&q=React 时:
页面显示 frontend 分类、online 筛选和 React 关键词。
切换筛选、提交搜索或翻页后,地址栏中的查询参数同步变化。
刷新页面或使用浏览器前进、后退,界面会按 URL 恢复。
切换“后端”分类时,路径变为 /products/backend,并保留当前查询条件。同步策略与关键边界
示例没有为页码和筛选再创建一套 React 状态,而是每次直接从 searchParams 计算界面。这样 URL 是单一事实来源,不会出现“控件显示第 2 页,但地址栏仍是第 1 页”的双状态冲突。
搜索输入框使用局部 draft,因为用户输入过程中不必每个字符都改写地址栏;提交表单后才把最终关键词写入 q。useEffect 则负责在浏览器历史变化时把 URL 中的关键词同步回输入框。
外部参数不可信,因此页码必须校验为正整数,状态值必须限制在允许集合中。示例用 safePage 防止页码超过总页数;生产项目还可以用 replace: true 把非法页码规范化回有效值。
更新查询参数时应复制现有 URLSearchParams,只修改目标字段。若每次重新创建空参数对象,容易在修改页码时意外丢失筛选和关键词。
先打开带完整参数的地址,确认控件和列表正确还原;再依次修改分类、状态、关键词和页码,观察 URL 是否只改变对应部分。最后使用刷新、前进和后退验证状态可恢复。