0Pricing
React Academy · 课时

管理 URL 搜索参数中的状态

使用 useSearchParams 将筛选、排序和分页状态同步到 URL。

管理 URL 搜索参数中的状态 是 CoddyKit 上的免费 React Academy 课时。 这是第 4 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 React Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 React Academy 课程共包含 4 节课。

为什么要将状态存储在 URL 中

筛选条件、搜索查询、排序顺序和分页信息都应放在 URL 中，这样用户就可以收藏、分享，并在返回时恢复到相同视图，而不会丢失状态。

useSearchParams 钩子

useSearchParams() 会返回当前的 URLSearchParams 实例和一个设置函数。它类似于 useState，但由 URL 查询字符串提供支持。

import { useSearchParams } from 'react-router-dom';

function ProductList() {
  const [searchParams, setSearchParams] = useSearchParams();
  const query = searchParams.get('q') || '';
  const page = Number(searchParams.get('page') || 1);
  // ...
}

读取单个参数

使用 searchParams.get('key') 读取一个值。如果参数不存在，它会返回 null，因此请提供一个备用值。

const sort = searchParams.get('sort') ?? 'name';
const order = searchParams.get('order') ?? 'asc';

不进行导航地写入参数

使用新的对象或更新函数调用 setSearchParams() 来更改参数。React Router 会更新 URL 并重新渲染，而不会进行完整导航。

function SortButton({ field }) {
  const [searchParams, setSearchParams] = useSearchParams();
  const handleClick = () => {
    setSearchParams(prev => {
      prev.set('sort', field);
      prev.set('page', '1');
      return prev;
    });
  };
  return <button onClick={handleClick}>Sort by {field}</button>;
}

更新时保留其他参数

使用 setSearchParams 的更新函数形式，这样您只会修改计划更改的参数，并保留其他所有参数。

setSearchParams(prev => {
  prev.set('q', newQuery);
  // 'sort' and 'page' are unchanged
  return prev;
});

将输入框与搜索参数同步

使用 URL 参数控制输入框的值，并在值发生变化时更新 URL，使二者保持同步。

function SearchBar() {
  const [params, setParams] = useSearchParams();
  const q = params.get('q') || '';
  return (
    <input
      value={q}
      onChange={e => setParams(prev => {
        prev.set('q', e.target.value);
        prev.set('page', '1');
        return prev;
      })}
    />
  );
}

搜索参数中的布尔标志

使用参数的存在与否（或字符串“1”/“0”）来表示界面布尔状态，例如面板是否打开或筛选条件是否启用。

const showFilters = searchParams.has('filters');

const toggleFilters = () => {
  setSearchParams(prev => {
    if (prev.has('filters')) prev.delete('filters');
    else prev.set('filters', '1');
    return prev;
  });
};

搜索参数中的数组值

URLSearchParams 支持同一个键对应多个值。使用 getAll('key') 将这些值作为数组读取。

// URL: /products?tag=react&tag=typescript
const tags = searchParams.getAll('tag'); // ['react', 'typescript']

// Setting multiple values:
const newParams = new URLSearchParams();
selectedTags.forEach(t => newParams.append('tag', t));
setSearchParams(newParams);

替换历史记录与推入历史记录

将 { replace: true } 作为 setSearchParams 的第二个参数传入，这样筛选条件的变化就不会大量占用浏览器历史记录栈。

setSearchParams(prev => { prev.set('q', val); return prev; }, { replace: true });

从参数派生状态

在组件顶部根据原始字符串参数计算派生值（例如解析后的整数或经过验证的枚举值），以便在整个组件中安全使用。

const rawPage = searchParams.get('page');
const page = Math.max(1, parseInt(rawPage || '1', 10));

const rawSort = searchParams.get('sort');
const sort = ['name', 'price', 'date'].includes(rawSort) ? rawSort : 'name';

使用搜索参数创建链接

在 Link 或 to 对象上使用 search 属性，导航到已设置特定查询参数的 URL。

<Link to={{ pathname: '/products', search: '?sort=price&order=asc' }}>
  Sort by Price
</Link>

快速检查

网址查询参数对象的哪个方法可以读取重复键（例如 ?tag=react&tag=ts）的所有值？

回顾

useSearchParams() 会将组件状态与 URL 查询字符串同步。使用更新函数形式保留其他参数，使用 { replace: true } 避免历史记录膨胀，并使用 getAll() 处理数组值参数。

常见问题解答

「管理 URL 搜索参数中的状态」课时是免费的吗？

是的 — 「管理 URL 搜索参数中的状态」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 React Academy 课程的其余内容，请升级到 CoddyKit PRO。 React Academy 课程共包含 4 节课。

「管理 URL 搜索参数中的状态」这节课中我会学到什么？

使用 useSearchParams 将筛选、排序和分页状态同步到 URL。 你通过在浏览器中直接运行的动手代码来练习 React Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 React Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 React Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 4 节课，共 4 节。

「管理 URL 搜索参数中的状态」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 React Academy 课中编写并运行代码吗？

能。每节 React Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

  1. 嵌套路由与 Outlet 布局
  2. 加载器与操作（数据路由 API）
  3. 受保护路由与身份验证守卫
  4. 管理 URL 搜索参数中的状态
← 返回 React Academy