React / 系统课时

读取查询参数

读取查询参数

本课使用页面的 searchParams 读取搜索词、页码和排序方式,并把不可信的 URL 字符串转换为安全的业务参数。完成后,同一个列表页即可响应多种筛选组合。

学习目标

  • 在服务端页面中读取异步 searchParams
  • 处理参数缺失、重复和格式错误
  • 为分页与排序设置可预测的默认值

查询参数适合表达什么

查询参数位于 ? 之后,例如 /products?keyword=phone&page=2&sort=price。它们适合表达可选状态:搜索词、筛选条件、页码和排序方式。改变这些参数通常不会改变资源类型,只会改变同一页面展示的数据集合。

页面接收到的值可能是字符串、字符串数组或 undefined。数组通常来自重复键,例如 ?tag=js&tag=react。业务代码不应假设用户一定传入单个合法值。

在服务端页面中规范化参数

下面的完整页面先取单值,再校验页码和排序字段。所有默认值都集中在解析阶段,后续查询逻辑只接收已经规范化的数据。

tsx
// app/products/page.tsx
type SearchParams = Promise<{
  keyword?: string | string[]
  page?: string | string[]
  sort?: string | string[]
}>

function first(value: string | string[] | undefined): string | undefined {
  return Array.isArray(value) ? value[0] : value
}

export default async function ProductsPage({
  searchParams,
}: {
  searchParams: SearchParams
}) {
  const raw = await searchParams
  const keyword = first(raw.keyword)?.trim() ?? ''
  const parsedPage = Number(first(raw.page) ?? '1')
  const page = Number.isInteger(parsedPage) && parsedPage > 0 ? parsedPage : 1

  const requestedSort = first(raw.sort)
  const sort = requestedSort === 'price' || requestedSort === 'newest'
    ? requestedSort
    : 'newest'

  return (
    <main>
      <h1>商品列表</h1>
      <p>搜索词:{keyword || '未指定'}</p>
      <p>页码:{page}</p>
      <p>排序:{sort}</p>
    </main>
  )
}

预期结果:合法参数按原值显示,非法页码和未知排序方式回退到默认值。

text
/products?keyword=phone&page=2&sort=price
搜索词:phone
页码:2
排序:price

/products?page=-3&sort=random
搜索词:未指定
页码:1
排序:newest

服务端属性与客户端 Hook

服务端页面优先使用 searchParams 属性,它便于在读取数据前完成筛选和分页。需要在客户端交互组件中响应当前 URL 时,可以使用 useSearchParams(),但该 Hook 只能用于客户端组件,并返回只读参数对象。

不要在共享布局中依赖页面查询参数,因为布局在客户端导航时可能被复用。需要随 URL 变化更新的筛选摘要,应放在页面中,或放进调用 useSearchParams() 的客户端组件。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

读取查询参数

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通