useSearchParams
useSearchParams hook 的 API 参考。
useSearchParams 是一个 Client Component hook,可让你读取当前 URL 的 查询字符串(query string)。
useSearchParams 返回 URLSearchParams 接口的只读版本。
'use client'
import { useSearchParams } from 'next/navigation'
export default function SearchBar() {
const searchParams = useSearchParams()
const search = searchParams.get('search')
// URL -> `/dashboard?search=my-project`
// `search` -> 'my-project'
return <>Search: {search}</>
}'use client'
import { useSearchParams } from 'next/navigation'
export default function SearchBar() {
const searchParams = useSearchParams()
const search = searchParams.get('search')
// URL -> `/dashboard?search=my-project`
// `search` -> 'my-project'
return <>Search: {search}</>
}参数#
const searchParams = useSearchParams()useSearchParams 不接受任何参数。
返回值#
useSearchParams 返回 URLSearchParams 接口的只读版本,其中包含用于读取 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是一个 Client Component hook,在 Server Components 中不受支持,以防止在部分渲染期间出现过期值。- 如果你想在 Server Component 中根据搜索参数获取数据,通常更好的做法是读取对应页面的
searchParamsprop。然后你可以通过 props 将它传递给该页面中的任何组件(Server 或 Client)。- 如果应用程序包含
/pages目录,useSearchParams将返回ReadonlyURLSearchParams | null。null值是为了迁移期间的兼容性,因为对于不使用getServerSideProps的页面,在预渲染期间无法获知搜索参数。
行为#
预渲染#
如果路由是预渲染的,调用 useSearchParams 将导致 Client Component 树直到最近的 Suspense 边界为止的部分都进行客户端渲染。
这使得路由的一部分可以被预渲染,而使用 useSearchParams 的动态部分则进行客户端渲染。
使用 Cache Components 时,只有当路由的其余部分被预渲染时,该边界才会进行客户端渲染。如果路由上的任何组件读取请求数据(例如 cookies()),Next.js 会在请求时在服务端使用该真实搜索参数渲染该边界。要让读取仅浏览器可用 API(例如 sessionStorage)的组件不参与服务端渲染,请改用 use(browser()),而不要依赖 useSearchParams 边界。
我们建议将使用 useSearchParams 的 Client Component 包裹在 <Suspense/> 边界中。这样可以让其之上的任何 Client Component 都被预渲染并作为初始 HTML 的一部分发送。
有关完整的修复选项和权衡,请参阅 Next.js 在 Suspense 之外的 Client Component 中遇到 URL 数据。
例如:
'use client'
import { useSearchParams } from 'next/navigation'
export default function SearchBar() {
const searchParams = useSearchParams()
const search = searchParams.get('search')
// 在预渲染期间,这不会记录在服务端
console.log(search)
return <>Search: {search}</>
}'use client'
import { useSearchParams } from 'next/navigation'
export default function SearchBar() {
const searchParams = useSearchParams()
const search = searchParams.get('search')
// 在预渲染期间,这不会记录在服务端
console.log(search)
return <>Search: {search}</>
}import { Suspense } from 'react'
import SearchBar from './search-bar'
// 作为 fallback 传递给 Suspense 边界的这个组件
// 将在初始 HTML 中渲染,以代替搜索栏。
// 当 React hydration 期间该值可用时,fallback
// 将被 `<SearchBar>` 组件替换。
function SearchBarFallback() {
return <>placeholder</>
}
export default function Page() {
return (
<>
<nav>
<Suspense fallback={<SearchBarFallback />}>
<SearchBar />
</Suspense>
</nav>
<h1>Dashboard</h1>
</>
)
}import { Suspense } from 'react'
import SearchBar from './search-bar'
// 作为 fallback 传递给 Suspense 边界的这个组件
// 将在初始 HTML 中渲染,以代替搜索栏。
// 当 React hydration 期间该值可用时,fallback
// 将被 `<SearchBar>` 组件替换。
function SearchBarFallback() {
return <>placeholder</>
}
export default function Page() {
return (
<>
<nav>
<Suspense fallback={<SearchBarFallback />}>
<SearchBar />
</Suspense>
</nav>
<h1>Dashboard</h1>
</>
)
}小知识:
- 在开发环境中,路由是按需渲染的,因此
useSearchParams不会 suspend,即使没有Suspense,一切也可能看起来正常工作。- 在生产构建期间,从 Client Component 调用
useSearchParams的静态页面必须包裹在Suspense边界中,否则构建会失败,并出现 Missing Suspense boundary with useSearchParams 错误。- 如果你希望路由进行动态渲染,最好先在 Server Component 中使用
connection函数等待传入的请求,这会将下面的所有内容排除在预渲染之外。请参阅动态渲染指南,了解是什么让路由成为动态路由。- 如果你已经在 Server Component 页面中,请考虑使用
searchParamsprop 并将值传递给 Client Component。- 你也可以将页面的
searchParamsprop 直接传递给 Client Component,并使用 React 的use()进行解包。尽管这会 suspend,因此该 Client Component 应该包裹在Suspense边界中。
动态渲染#
如果路由是动态渲染的,在 Client Component 的初始服务端渲染期间,useSearchParams 在服务端是可用的。
例如:
'use client'
import { useSearchParams } from 'next/navigation'
export default function SearchBar() {
const searchParams = useSearchParams()
const search = searchParams.get('search')
// 这会在初次渲染期间记录在服务端
// 并在后续导航时记录在客户端。
console.log(search)
return <>Search: {search}</>
}'use client'
import { useSearchParams } from 'next/navigation'
export default function SearchBar() {
const searchParams = useSearchParams()
const search = searchParams.get('search')
// 这会在初次渲染期间记录在服务端
// 并在后续导航时记录在客户端。
console.log(search)
return <>Search: {search}</>
}import { connection } from 'next/server'
import SearchBar from './search-bar'
export default async function Page() {
await connection()
return (
<>
<nav>
<SearchBar />
</nav>
<h1>Dashboard</h1>
</>
)
}import { connection } from 'next/server'
import SearchBar from './search-bar'
export default async function Page() {
await connection()
return (
<>
<nav>
<SearchBar />
</nav>
<h1>Dashboard</h1>
</>
)
}小知识:
- 以前,在页面上设置
export const dynamic = 'force-dynamic'用于强制动态渲染。现在更推荐使用connection(),因为它在语义上将动态渲染与传入的请求关联起来。
Server Components#
页面#
要在页面(Server Components)中访问搜索参数,请使用 searchParams prop。
布局#
与页面不同,布局(Server Components)不会接收 searchParams prop。这是因为共享布局在导航时不会重新渲染,这可能导致导航之间出现过期值。查看详细说明。
相反,请在 Client Component 中使用页面的 searchParams prop 或 useSearchParams hook,它们会在客户端使用最新的 searchParams 重新渲染。
示例#
更新 searchParams#
你可以使用 useRouter 或 Link 来设置新的 searchParams。导航执行后,当前的 page.js 将接收到更新后的 searchParams prop。
'use client'
export default function ExampleClientComponent() {
const router = useRouter()
const pathname = usePathname()
const searchParams = useSearchParams()
// 通过将当前的 searchParams 与提供的键/值对合并,
// 得到一个新的 searchParams 字符串
const createQueryString = useCallback(
(name: string, value: string) => {
const params = new URLSearchParams(searchParams.toString())
params.set(name, value)
return params.toString()
},
[searchParams]
)
return (
<>
<p>Sort By</p>
<button
onClick={() => {
// <pathname>?sort=asc
router.push(pathname + '?' + createQueryString('sort', 'asc'))
}}
>
ASC
</button>
<Link
href={
// <pathname>?sort=desc
pathname + '?' + createQueryString('sort', 'desc')
}
>
DESC
</Link>
</>
)
}'use client'
export default function ExampleClientComponent() {
const router = useRouter()
const pathname = usePathname()
const searchParams = useSearchParams()
// 通过将当前的 searchParams 与提供的键/值对合并,
// 得到一个新的 searchParams 字符串
const createQueryString = useCallback(
(name, value) => {
const params = new URLSearchParams(searchParams)
params.set(name, value)
return params.toString()
},
[searchParams]
)
return (
<>
<p>Sort By</p>
<button
onClick={() => {
// <pathname>?sort=asc
router.push(pathname + '?' + createQueryString('sort', 'asc'))
}}
>
ASC
</button>
<Link
href={
// <pathname>?sort=desc
pathname + '?' + createQueryString('sort', 'desc')
}
>
DESC
</Link>
</>
)
}版本历史#
| 版本 | 变更 |
|---|---|
v13.0.0 | 引入 useSearchParams。 |