在 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 (
<>
导航并修改查询参数：
{/* 使用 useRouter 进行客户端导航 */}
{/* 使用 组件进行声明式导航 */}
按降序排序 (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 (
);
}
在客户端组件中读取
对于客户端组件，你需要使用 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 (
客户端组件中的查询参数
{category && 分类: {category}
}
{page && 当前页码: {page}
}
{/* 更多客户端交互 */}
);
}useSearchParams 返回一个 URLSearchParams 实例，因此你可以使用其所有标准方法，如 get(), getAll(), has(), forEach() 等。
注意事项与最佳实践
- 客户端与服务器渲染的区分： searchParams prop 适用于服务器组件，在服务器端渲染时即可获取参数。useSearchParams 钩子则只能在客户端组件中使用，因为它依赖于浏览器环境的 window.location。
- 不可变性： URLSearchParams 对象是不可变的。每次 set()、delete() 或其他修改操作都会返回一个新的 URLSearchParams 实例。因此，在构建查询字符串时，请确保使用最新的实例。
- 通用辅助函数： 建议将构建和更新查询字符串的逻辑封装成一个通用的辅助函数，以便在整个应用中复用，提高代码的可维护性。例如，可以创建一个函数，它接受当前 searchParams 对象和要修改的键值对，然后返回新的查询字符串。
- 编码： URLSearchParams 会自动处理 URL 编码和解码，因此通常无需手动进行 encodeURIComponent 或 decodeURIComponent。
总结
Next.js app 目录下的路由管理方式带来了更强大的能力和更清晰的职责划分。虽然 router.push 在查询参数处理上变得更“原始”，但通过结合 URLSearchParams 和 next/navigation 提供的钩子，我们依然能够高效、灵活地管理 URL 查询参数。理解这些变化并采用正确的实践，将有助于开发者更好地利用 Next.js app 路由的优势，构建高性能和可维护的应用。
