React / 系统课时

路由参数与查询条件

路由参数与查询条件

本课构建一个可运行的商品列表页:分类放在路径参数中,页码、状态和关键词放在查询字符串中,并让界面操作持续更新 URL,从而支持刷新恢复、复制链接和浏览器前进后退。

学习目标

  • 使用 useParams 读取动态路径参数
  • 使用 useSearchParams 读取和更新查询字符串
  • 让分页、筛选与搜索状态以 URL 为单一事实来源

参数应该放在哪里

路径参数用于标识页面主体,例如 /products/frontend 中的 frontend;查询参数用于描述同一页面的查看方式,例如 ?page=2&status=online&q=React。

判断标准很简单:改变参数后若进入了另一类资源,优先使用路径参数;若仍是同一资源列表,只改变排序、筛选、分页或搜索条件,优先使用查询参数。

路径参数与查询条件的数据同步流程

完整实现

下面的示例可直接替换 Vite React TypeScript 项目的 src/main.tsx。它使用内存数据模拟列表,不依赖后端接口。

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>,
);

预期结果

text
访问 /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 是否只改变对应部分。最后使用刷新、前进和后退验证状态可恢复。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

路由参数与查询条件

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通