NNext.js 中文网 GitHub

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 就绪后按照上述规则更新属性。

例如:

路由URLuseParams()
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。
Next.js 中文网