如何将react-router-dom的参数复选框迁移至Next.js 13

核心适配思路 #

Next.js 13 App Router 用 useSearchParams 和 useRouter（均来自 next/navigation）替代了 React Router 的对应钩子，核心逻辑和 React Router 一致，但需要注意客户端组件限制和路由更新的语法差异。

原 React Router 代码（参考） #

假设你原来的实现是这样的：

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

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

  const handleCheckboxChange = (e) => {
    const { name, checked } = e.target;
    const params = new URLSearchParams(searchParams);
    
    checked ? params.append(name, 'true') : params.delete(name);
    navigate({ search: params.toString() }, { replace: true });
  };

  const isChecked = (name) => searchParams.get(name) === 'true';

  return (
    <div>
      <label>
        <input type="checkbox" name="showActive" checked={isChecked('showActive')} onChange={handleCheckboxChange} />
        显示活跃项
      </label>
      <label>
        <input type="checkbox" name="showArchived" checked={isChecked('showArchived')} onChange={handleCheckboxChange} />
        显示已归档项
      </label>
    </div>
  );
};

Next.js 13 适配代码 #

'use client'; // 必须添加：所有使用客户端钩子的组件都需要声明为客户端组件

import { useSearchParams, useRouter } from 'next/navigation';

const FilterComponent = () => {
  const searchParams = useSearchParams();
  const router = useRouter();

  const handleCheckboxChange = (e) => {
    const { name, checked } = e.target;
    // 复制当前搜索参数（Next.js 返回的 searchParams 是只读对象，必须创建副本）
    const newParams = new URLSearchParams(searchParams.toString());

    if (checked) {
      newParams.set(name, 'true'); // 单值用 set，多值场景用 append
    } else {
      newParams.delete(name);
    }

    // 更新路由：replace: true 替换当前历史记录，避免回退时重复触发筛选
    router.push(
      {
        pathname: window.location.pathname, // 保持当前路径
        search: newParams.toString(),
      },
      {
        scroll: false, // 保持当前滚动位置，提升体验
        replace: true,
      }
    );
  };

  const isChecked = (name) => searchParams.get(name) === 'true';

  return (
    <div className="space-y-2">
      <label className="flex items-center gap-2">
        <input
          type="checkbox"
          name="showActive"
          checked={isChecked('showActive')}
          onChange={handleCheckboxChange}
        />
        显示活跃项
      </label>
      <label className="flex items-center gap-2">
        <input
          type="checkbox"
          name="showArchived"
          checked={isChecked('showArchived')}
          onChange={handleCheckboxChange}
        />
        显示已归档项
      </label>
    </div>
  );
};

export default FilterComponent;

关键注意事项 #

• 客户端组件声明：必须在组件顶部添加 'use client';，因为 useSearchParams 和 useRouter 是客户端专属钩子，无法在服务器组件中使用。
• 只读搜索参数：Next.js 返回的 searchParams 是只读对象，不能直接修改，必须通过 new URLSearchParams(searchParams.toString()) 创建可修改副本。
• 多值参数处理：如果你的复选框是多值场景（比如多选分类），把 set 换成 append，读取时用 searchParams.getAll('category') 获取参数数组。
• 服务器组件读取参数：如果需要在服务器组件（比如 page.js）中读取筛选参数，直接使用组件接收的 searchParams prop：

  // app/filters/page.js（服务器组件）
  export default function FiltersPage({ searchParams }) {
    const showActive = searchParams?.showActive === 'true';
    return (
      <div>
        <h1>筛选结果</h1>
        <FilterComponent />
        {showActive && <p>展示活跃内容</p>}
      </div>
    );
  }
  

适配总结 #

1. 替换导入：将 React Router 的钩子换成 next/navigation 提供的对应钩子。
2. 添加客户端声明：确保组件是客户端组件。
3. 调整参数更新逻辑：创建可修改的参数副本，用 router.push 替换 navigate，并配置合适的路由选项。
4. 服务器组件读取参数：直接使用 searchParams prop，交互逻辑始终放在客户端组件。

内容的提问来源于stack exchange，提问作者yazanslaim