useSearchParams
Pages Router 中 useSearchParams hook 的 API 参考。
useSearchParams 是一个 hook,可让你读取当前 URL 的查询字符串。
useSearchParams 返回 URLSearchParams 接口的只读版本。
pages/dashboard.tsx
import { useSearchParams } from 'next/navigation'
export default function Dashboard() {
const searchParams = useSearchParams()
if (!searchParams) {
// 当搜索参数尚不可用时渲染回退 UI
return null
}
const search = searchParams.get('search')
// URL -> `/dashboard?search=my-project`
// `search` -> 'my-project'
return <>Search: {search}</>
}pages/dashboard.js
import { useSearchParams } from 'next/navigation'
export default function Dashboard() {
const searchParams = useSearchParams()
if (!searchParams) {
// 当搜索参数尚不可用时渲染回退 UI
return null
}
const search = searchParams.get('search')
// URL -> `/dashboard?search=my-project`
// `search` -> 'my-project'
return <>Search: {search}</>
}参数#
tsx
const searchParams = useSearchParams()useSearchParams 不接受任何参数。
返回值#
useSearchParams 返回 URLSearchParams 接口的只读版本,或者在预渲染期间返回 null。
该接口包含用于读取 URL 查询字符串的实用方法:
URLSearchParams.get():返回与搜索参数关联的第一个值。例如:
| URL | searchParams.get("a") |
|---|---|
/dashboard?a=1 | '1' |
/dashboard?a= | '' |
/dashboard?b=3 | null |
/dashboard?a=1&a=2 | '1' - 使用 getAll() 获取所有值 |
URLSearchParams.has():返回一个布尔值,指示给定参数是否存在。例如:
| URL | searchParams.has("a") |
|---|---|
/dashboard?a=1 | true |
/dashboard?b=3 | false |
- 了解
URLSearchParams的其他只读方法,包括getAll()、keys()、values()、entries()、forEach()和toString()。
小知识:
useSearchParams是一个 React Hook,不能与类一起使用。
行为#
预渲染期间的行为#
对于静态优化的页面(不使用 getServerSideProps),useSearchParams 在预渲染期间将返回 null。hydration 之后,该值将更新为实际的搜索参数。
这是因为搜索参数依赖于请求,在静态生成期间无法获知。
pages/dashboard.tsx
import { useSearchParams } from 'next/navigation'
export default function Dashboard() {
const searchParams = useSearchParams()
if (!searchParams) {
// 当搜索参数正在加载时返回回退 UI
// 这可以防止 hydration 不匹配
return <DashboardSkeleton />
}
const search = searchParams.get('search')
return <>Search: {search}</>
}pages/dashboard.js
import { useSearchParams } from 'next/navigation'
export default function Dashboard() {
const searchParams = useSearchParams()
if (!searchParams) {
// 当搜索参数正在加载时返回回退 UI
// 这可以防止 hydration 不匹配
return <DashboardSkeleton />
}
const search = searchParams.get('search')
return <>Search: {search}</>
}与 getServerSideProps 一起使用#
使用 getServerSideProps 时,页面会在每次请求时进行服务端渲染,useSearchParams 将立即返回实际的搜索参数:
pages/dashboard.tsx
import { useSearchParams } from 'next/navigation'
export default function Dashboard() {
const searchParams = useSearchParams()
// 使用 getServerSideProps 时,这个回退永远不会渲染,因为
// searchParams 在服务端始终可用。不过,保留
// 这个回退可以让该组件在其他页面上复用
// 这些页面可能不使用 getServerSideProps。
if (!searchParams) {
return null
}
const search = searchParams.get('search')
return <>Search: {search}</>
}
export async function getServerSideProps() {
return { props: {} }
}pages/dashboard.js
import { useSearchParams } from 'next/navigation'
export default function Dashboard() {
const searchParams = useSearchParams()
// 使用 getServerSideProps 时,这个回退永远不会渲染,因为
// searchParams 在服务端始终可用。不过,保留
// 这个回退可以让该组件在其他页面上复用
// 这些页面可能不使用 getServerSideProps。
if (!searchParams) {
return null
}
const search = searchParams.get('search')
return <>Search: {search}</>
}
export async function getServerSideProps() {
return { props: {} }
}示例#
更新搜索参数#
你可以使用 useRouter hook 来更新搜索参数:
pages/dashboard.tsx
import { useRouter } from 'next/router'
import { useSearchParams } from 'next/navigation'
import { useCallback } from 'react'
export default function Dashboard() {
const router = useRouter()
const searchParams = useSearchParams()
const createQueryString = useCallback(
(name: string, value: string) => {
const params = new URLSearchParams(searchParams?.toString())
params.set(name, value)
return params.toString()
},
[searchParams]
)
if (!searchParams) {
return null
}
return (
<>
<p>Sort By</p>
<button
onClick={() => {
router.push(router.pathname + '?' + createQueryString('sort', 'asc'))
}}
>
ASC
</button>
<button
onClick={() => {
router.push(router.pathname + '?' + createQueryString('sort', 'desc'))
}}
>
DESC
</button>
</>
)
}pages/dashboard.js
import { useRouter } from 'next/router'
import { useSearchParams } from 'next/navigation'
import { useCallback } from 'react'
export default function Dashboard() {
const router = useRouter()
const searchParams = useSearchParams()
const createQueryString = useCallback(
(name, value) => {
const params = new URLSearchParams(searchParams?.toString())
params.set(name, value)
return params.toString()
},
[searchParams]
)
if (!searchParams) {
return null
}
return (
<>
<p>Sort By</p>
<button
onClick={() => {
router.push(router.pathname + '?' + createQueryString('sort', 'asc'))
}}
>
ASC
</button>
<button
onClick={() => {
router.push(router.pathname + '?' + createQueryString('sort', 'desc'))
}}
>
DESC
</button>
</>
)
}与 App Router 共享组件#
来自 next/navigation 的 useSearchParams 在 Pages Router 和 App Router 中都可用。这使你可以创建在任一上下文中都能工作的共享组件:
components/search-bar.tsx
import { useSearchParams } from 'next/navigation'
// 该组件在 pages/ 和 app/ 中都可用
export function SearchBar() {
const searchParams = useSearchParams()
if (!searchParams) {
// Pages Router 在预渲染期间的回退
return <input defaultValue="" placeholder="Search..." />
}
const search = searchParams.get('search') ?? ''
return <input defaultValue={search} placeholder="Search..." />
}components/search-bar.js
import { useSearchParams } from 'next/navigation'
// 该组件在 pages/ 和 app/ 中都可用
export function SearchBar() {
const searchParams = useSearchParams()
if (!searchParams) {
// Pages Router 在预渲染期间的回退
return <input defaultValue="" placeholder="Search..." />
}
const search = searchParams.get('search') ?? ''
return <input defaultValue={search} placeholder="Search..." />
}小知识:在 App Router 中使用此组件时,请将其包裹在
<Suspense>边界中,以支持预渲染。
版本历史#
| 版本 | 变更 |
|---|---|
v13.0.0 | 引入 useSearchParams。 |