Next.js App Router 中管理 URL 查询参数的指南

"use client"; // 标记为客户端组件

import Link from "next/link";
import { useRouter } from "next/navigation"; // 从 next/navigation 导入 useRouter

export default function QueryParamExample() {
  const router = useRouter();

  /**
   * 辅助函数：根据名称和值创建或更新查询字符串
   * @param {string} name - 查询参数的名称
   * @param {string} value - 查询参数的值
   * @returns {string} 格式化后的查询字符串
   */
  const createQueryString = (name, value) => {
    // 实例化 URLSearchParams，可以基于当前 URL 的查询参数进行初始化
    // 例如：const params = new URLSearchParams(window.location.search);
    const params = new URLSearchParams();
    params.set(name, value); // 设置或更新指定参数的值

    return params.toString(); // 将参数对象转换为字符串
  };

  /**
   * 辅助函数：基于当前 URL 查询参数更新指定参数
   * @param {string} name - 要更新的参数名
   * @param {string} value - 要设置的参数值
   * @returns {string} 包含更新后参数的完整查询字符串
   */
  const updateQueryString = (name, value) => {
    // 获取当前 URL 的查询参数
    const currentParams = new URLSearchParams(window.location.search);
    currentParams.set(name, value); // 更新或添加参数
    return currentParams.toString();
  };

  return (
    <>
      <h3>导航并修改查询参数：</h3>
      {/* 使用 useRouter 进行客户端导航 */}
      <button
        onClick={() => {
          // 示例：添加或修改 'sort' 参数为 'asc'
          router.push("/posts" + "?" + createQueryString("sort", "asc"));
        }}
      >
        按升序排序 (useRouter)
      </button>
      <br />
      <button
        onClick={() => {
          // 示例：在现有参数基础上，修改 'page' 参数为 '2'
          router.push("/products" + "?" + updateQueryString("page", "2"));
        }}
      >
        前往第二页 (useRouter)
      </button>
      <br />

      {/* 使用 <Link> 组件进行声明式导航 */}
      <Link href={"/posts" + "?" + createQueryString("sort", "desc")}>
        按降序排序 (Link)
      </Link>
      <br />
      <Link href={"/products" + "?" + updateQueryString("category", "electronics")}>
        查看电子产品 (Link)
      </Link>
    </>
  );
}

// app/posts/page.js (服务器组件)

/**
 * Page 组件接收 searchParams prop，其中包含 URL 查询参数。
 * @param {Object} props
 * @param {Object} props.searchParams - URL 查询参数对象
 */
export default function PostsPage({ searchParams }) {
  // 示例：获取 'sort' 参数的值
  const sortBy = searchParams.sort;

  return (
    <div>
      <h1>文章列表</h1>
      {sortBy && <p>当前排序方式: {sortBy}</p>}
      {/* 其他内容 */}
    </div>
  );
}

"use client"; // 标记为客户端组件

import { useSearchParams } from "next/navigation";

export default function ClientComponentWithSearchParams() {
  const searchParams = useSearchParams();

  // 使用 .get() 方法获取特定参数的值
  const category = searchParams.get("category");
  const page = searchParams.get("page");

  return (
    <div>
      <h2>客户端组件中的查询参数</h2>
      {category && <p>分类: {category}</p>}
      {page && <p>当前页码: {page}</p>}
      {/* 更多客户端交互 */}
    </div>
  );
}