本文介绍如何使用 useSearchParams 钩子将组件内部状态（如卧室数、浴室数、车位数）实时映射为浏览器 URL 的查询参数，并支持点击搜索时精准构建 /rent/?bedrooms=2&parking=1 类型的链接。

本文介绍如何使用 usesearchparams 钩子将组件内部状态（如卧室数、浴室数、车位数）实时映射为浏览器 url 的查询参数，并支持点击搜索时精准构建 /rent/?bedrooms=2&parking=1 类型的链接。

在构建可分享、可回退的筛选功能（如租房/买房搜索页）时，将 UI 状态与 URL 同步至关重要。React Router v6.8+ 提供的 useSearchParams 钩子正是为此场景设计的专业解决方案——它不仅允许你读取当前 URL 中的查询参数，还能以声明式方式更新它们，同时保持路由状态一致性。

以下是一个完整、可直接复用的实现示例：

shopify-app-react-router

构建 Shopify 嵌入式应用（Embedded App）的开发技能：基于 @shopify/shopify-app-react-router + React Router v7 + Admin API 2026-04。覆盖 shopifyApp 配置、authenticate.admin 的 GraphQL/REST 调用、Webhook 校验、Session 存储、订阅计费、App Bridge 导航、部署，并新增：适用场景判断、安全最佳实践、错误处理与容错、最佳实践、常见问题 FAQ、高级场景。G

下载

import { useState, useEffect } from 'react';
import { useSearchParams, useNavigate } from 'react-router-dom';

const FilterOption = () => {
  const [searchParams, setSearchParams] = useSearchParams();
  const navigate = useNavigate();

  // 初始化状态：从 URL 参数中读取初始值（若存在），否则设为 0
  const [postCode, setPostCode] = useState<string | undefined>(
    searchParams.get('postcode') || undefined
  );
  const [price, setPrice] = useState<string | undefined>(
    searchParams.get('price') || undefined
  );
  const [bedroomCount, setBedroomCount] = useState<number>(
    Number(searchParams.get('bedrooms') ?? 0)
  );
  const [bathroomCount, setBathroomCount] = useState<number>(
    Number(searchParams.get('bathrooms') ?? 0)
  );
  const [parkingCount, setParkingCount] = useState<number>(
    Number(searchParams.get('parking') ?? 0)
  );

  // （可选）监听 URL 变化，自动同步 state（适用于外部跳转或浏览器前进/后退）
  useEffect(() => {
    setBedroomCount(Number(searchParams.get('bedrooms') ?? 0));
    setBathroomCount(Number(searchParams.get('bathrooms') ?? 0));
    setParkingCount(Number(searchParams.get('parking') ?? 0));
    setPostCode(searchParams.get('postcode') || undefined);
    setPrice(searchParams.get('price') || undefined);
  }, [searchParams]);

  const searchHandler = () => {
    // 构建干净的查询参数：仅保留非零值，避免 /rent/?bedrooms=0&bathrooms=1 这类冗余
    const newParams = new URLSearchParams();

    if (bedroomCount > 0) newParams.set('bedrooms', bedroomCount.toString());
    if (bathroomCount > 0) newParams.set('bathrooms', bathroomCount.toString());
    if (parkingCount > 0) newParams.set('parking', parkingCount.toString());
    if (postCode) newParams.set('postcode', postCode);
    if (price) newParams.set('price', price);

    // 更新 URL（不触发页面刷新），并可选地导航到目标路径
    setSearchParams(newParams);
    // 若需强制跳转到 /rent/ 路径（而非当前路径），可改用：
    // navigate(`/rent/?${newParams.toString()}`, { replace: false });
  };

  return (
    <div>
      <label>
        卧室数：
        <input
          type="number"
          value={bedroomCount}
          onChange={(e) => setBedroomCount(Number(e.target.value))}
        />
      </label>
      <label>
        浴室数：
        <input
          type="number"
          value={bathroomCount}
          onChange={(e) => setBathroomCount(Number(e.target.value))}
        />
      </label>
      <label>
        车位数：
        <input
          type="number"
          value={parkingCount}
          onChange={(e) => setParkingCount(Number(e.target.value))}
        />
      </label>
      <button onClick={searchHandler}>搜索</button>
    </div>
  );
};

export default FilterOption;

关键要点与注意事项：

• ✅ 初始化对齐：组件首次加载时，应从 searchParams 读取初始值，确保 URL → State 的单向同步；
• ✅ 条件写入：推荐在 searchHandler 中显式构造 URLSearchParams 对象，仅添加有效参数（如 count > 0），避免 ?bedrooms=0 这类无意义参数；
• ⚠️ 类型安全：searchParams.get() 返回 string | null，务必做空值处理（如 ?? '0'）并转换为数字，防止 NaN；
• ? 双向同步增强：如需支持用户手动修改地址栏后自动更新表单（例如分享链接后打开），应配合 useEffect 监听 searchParams 变化；
• ? 路径控制：setSearchParams 默认在当前路径下更新查询参数；若需跳转至固定路径（如 /rent/），请结合 useNavigate 显式调用。

通过该方案，你的筛选组件即可天然支持：URL 分享、浏览器前进/后退、SEO 友好、服务端预渲染兼容等现代 Web 应用核心能力。