nuqs
类型安全的 URL 搜索参数状态管理
安装
npx shadcn@latest add https://ssp-ui-registry-staging.sh3.agoralab.co/r/nuqs.jsonyarn dlx shadcn@latest add https://ssp-ui-registry-staging.sh3.agoralab.co/r/nuqs.jsonpnpx shadcn@latest add https://ssp-ui-registry-staging.sh3.agoralab.co/r/nuqs.jsonbunx shadcn@latest add https://ssp-ui-registry-staging.sh3.agoralab.co/r/nuqs.json官方文档
简介
nuqs 是类型安全的 URL 搜索参数状态管理库，让你可以像使用 useState 一样管理 URL 参数。
Adapter 配置
Use Case：Table 分页与筛选
nuqs 最常见的场景是和数据请求 hook（如 use-cancelable-swr / use-cancelable-query）联动，实现 URL 参数驱动的数据获取。
场景：
- 用户翻页时，URL 变为
?page=2 - 用户刷新页面，自动恢复到第 2 页
- 用户分享链接，对方打开就是第 2 页
示例：分页 Table
import { parseAsInteger, parseAsString, useQueryState } from 'nuqs'
import { useCancelableSwr } from '@/hook/use-cancelable-swr'
function ProductTable() {
// URL 参数状态
const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1))
const [search, setSearch] = useQueryState('q', parseAsString.withDefault(''))
// 数据请求：URL 参数作为 key，参数变化自动重新请求
const [{ data, isLoading }] = useCancelableSwr<{ items: Product[]; total: number }>(
{
url: `/api/products?page=${page}&q=${search}`,
key: ['products', { page, search }]
},
undefined,
{ keepPreviousData: true } // 翻页时保持旧数据，避免表格闪烁
)
return (
<div>
<input
value={search}
onChange={(e) => {
setSearch(e.target.value)
setPage(1) // 搜索时重置到第一页
}}
placeholder="搜索产品..."
/>
<table>
{/* 渲染 data.items */}
</table>
<Pagination
current={page}
total={data?.total ?? 0}
onChange={setPage}
/>
</div>
)
}关键点
| 要点 | 说明 |
|---|---|
| URL 作为 Single Source of Truth | 分页/筛选状态保存在 URL，而不是组件 state |
| key 包含 URL 参数 | 确保参数变化时触发重新请求 |
| keepPreviousData: true | 翻页时保持旧数据显示，避免表格闪烁 |
| 可分享、可刷新 | 用户刷新页面或分享链接都能恢复状态 |
更多用法
请参考 官方文档。