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() 的客户端组件。
按自己的节奏,确认真正理解。