Next.js查询参数管理技巧分享

## Next.js App Router 查询参数管理全攻略：告别传统方式，玩转URLSearchParams 还在为Next.js 13.4+ app 目录中 `router.push` 方法不再直接支持 `query` 对象而烦恼吗？本文为你详细解读如何在新的路由机制下高效管理 URL 查询参数。我们将深入探讨如何利用 JavaScript 内置的 `URLSearchParams` 接口构建、修改查询字符串，并通过 `useRouter` 或 `` 组件实现页面导航。同时，文章还将介绍如何在服务器组件中使用 `searchParams` prop 以及在客户端组件中使用 `useSearchParams` 钩子来读取查询参数。掌握这些技巧，让你在 Next.js app 路由中轻松实现灵活、强大的查询参数操作，构建更具用户体验的 Web 应用。

本文详细介绍了在 Next.js 13.4 及更高版本的 app 目录中如何高效地管理 URL 查询参数。针对 router.push 方法在 app 路由中仅接受字符串 href 的变化，教程演示了如何利用 URLSearchParams 构建和修改查询字符串，并通过 useRouter 或 组件进行导航。同时，文章也涵盖了在服务器组件中使用 searchParams prop 以及在客户端组件中使用 useSearchParams 钩子来读取查询参数的方法，旨在提供一套完整的查询参数操作解决方案。

在 Next.js 的 pages 目录中，开发者习惯于通过向 router.push 传递一个包含 query 对象的参数来方便地更新 URL 查询参数。然而，随着 Next.js 13.4 引入的 app 目录，路由行为发生了显著变化。在 app 目录中，router.push(href: string) 方法现在仅接受一个字符串形式的 href 参数。这意味着，如果需要添加或修改 URL 查询参数，开发者必须手动构建完整的 URL 字符串，包括路径和查询部分。

构建和修改查询参数

由于 router.push 不再直接支持 query 对象，我们需要一种标准的方式来构建 URL 查询字符串。JavaScript 内置的 URLSearchParams 接口是处理 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>
    </>
  );
}

在上述代码中，createQueryString 函数用于从零开始构建一个查询字符串，而 updateQueryString 函数则用于在现有查询参数的基础上进行修改。通过将生成的查询字符串拼接到目标路径后面，我们可以实现带有查询参数的导航。

读取查询参数

在 app 目录中，读取 URL 查询参数的方式有两种，取决于组件的类型（服务器组件或客户端组件）。

在服务器组件中读取

对于服务器组件（例如 app/posts/page.js），Next.js 会自动将 URL 的查询参数作为 searchParams prop 传递给 Page 组件。这个 searchParams 是一个只读对象，包含了所有的查询参数键值对。

// 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>
  );
}

在客户端组件中读取

对于客户端组件，你需要使用 next/navigation 提供的 useSearchParams 钩子。这个钩子允许你在客户端组件中访问和操作 URL 的查询参数。

"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>
  );
}

useSearchParams 返回一个 URLSearchParams 实例，因此你可以使用其所有标准方法，如 get(), getAll(), has(), forEach() 等。

注意事项与最佳实践

1. 客户端与服务器渲染的区分： searchParams prop 适用于服务器组件，在服务器端渲染时即可获取参数。useSearchParams 钩子则只能在客户端组件中使用，因为它依赖于浏览器环境的 window.location。
2. 不可变性： URLSearchParams 对象是不可变的。每次 set()、delete() 或其他修改操作都会返回一个新的 URLSearchParams 实例。因此，在构建查询字符串时，请确保使用最新的实例。
3. 通用辅助函数： 建议将构建和更新查询字符串的逻辑封装成一个通用的辅助函数，以便在整个应用中复用，提高代码的可维护性。例如，可以创建一个函数，它接受当前 searchParams 对象和要修改的键值对，然后返回新的查询字符串。
4. 编码： URLSearchParams 会自动处理 URL 编码和解码，因此通常无需手动进行 encodeURIComponent 或 decodeURIComponent。

总结

Next.js app 目录下的路由管理方式带来了更强大的能力和更清晰的职责划分。虽然 router.push 在查询参数处理上变得更“原始”，但通过结合 URLSearchParams 和 next/navigation 提供的钩子，我们依然能够高效、灵活地管理 URL 查询参数。理解这些变化并采用正确的实践，将有助于开发者更好地利用 Next.js app 路由的优势，构建高性能和可维护的应用。

到这里，我们也就讲完了《Next.js查询参数管理技巧分享》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！