useParams
useParams Hook 的 API 参考。
useParams 是一个 Client Component Hook,可让你读取由当前 URL 填充的路由动态参数。
app/example-client-component.tsx
'use client'
import { useParams } from 'next/navigation'
export default function ExampleClientComponent() {
const params = useParams<{ tag: string; item: string }>()
// 路由 -> /shop/[tag]/[item]
// URL -> /shop/shoes/nike-air-max-97
// `params` -> { tag: 'shoes', item: 'nike-air-max-97' }
console.log(params)
return '...'
}app/example-client-component.js
'use client'
import { useParams } from 'next/navigation'
export default function ExampleClientComponent() {
const params = useParams()
// 路由 -> /shop/[tag]/[item]
// URL -> /shop/shoes/nike-air-max-97
// `params` -> { tag: 'shoes', item: 'nike-air-max-97' }
console.log(params)
return '...'
}参数#
tsx
const params = useParams()useParams 不接受任何参数。
返回值#
useParams 返回一个对象,其中包含当前路由已填充的动态参数。
- 对象中的每个属性都是一个活动的动态段。
- 属性名是段的名称,属性值是该段被填充的内容。
- 根据动态段的类型,属性值将是一个
string或string数组。 - 如果路由不包含动态参数,
useParams将返回一个空对象。 - 如果在 Pages Router 中使用,
useParams在初始渲染时将返回null,并在 router 就绪后按照上述规则更新属性。
例如:
| 路由 | URL | useParams() |
|---|---|---|
app/shop/page.js | /shop | {} |
app/shop/[slug]/page.js | /shop/1 | { slug: '1' } |
app/shop/[tag]/[item]/page.js | /shop/1/2 | { tag: '1', item: '2' } |
app/shop/[...slug]/page.js | /shop/1/2 | { slug: ['1', '2'] } |
行为#
Cache Components#
当启用 cacheComponents 时,useParams 可能需要一个 Suspense 边界。这取决于参数能否在预渲染期间解析。
- 静态路由以及带有
generateStaticParams的路由:每个动态参数在构建时都是已知的。useParams在服务器上解析,不需要Suspense边界。 - 动态参数未被
generateStaticParams覆盖的路由:参数直到请求时才已知。useParams会挂起(suspend)。将组件(或其父组件)包裹在Suspense边界中,以便其回退内容可以在预渲染期间渲染;否则,构建会失败。
有关完整的修复方案和权衡,请参阅 Next.js 在 Suspense 之外的 Client Component 中遇到 URL 数据。
版本历史#
| 版本 | 变更 |
|---|---|
v13.3.0 | 引入 useParams。 |