NNext.js 中文网 GitHub

useParams

Pages Router 中 useParams Hook 的 API 参考。

useParams 是一个 Hook,可让你读取由当前 URL 填充的路由动态参数。

pages/shop/[slug].tsx
import { useParams } from 'next/navigation'

export default function ShopPage() {
  const params = useParams<{ slug: string }>()

  if (!params) {
    // 当 params 尚不可用时渲染后备 UI
    return null
  }

  // 路由 -> /shop/[slug]
  // URL -> /shop/shoes
  // `params` -> { slug: 'shoes' }
  return <>Shop: {params.slug}</>
}
pages/shop/[slug].js
import { useParams } from 'next/navigation'

export default function ShopPage() {
  const params = useParams()

  if (!params) {
    // 当 params 尚不可用时渲染后备 UI
    return null
  }

  // 路由 -> /shop/[slug]
  // URL -> /shop/shoes
  // `params` -> { slug: 'shoes' }
  return <>Shop: {params.slug}</>
}

参数#

tsx
const params = useParams()

useParams 不接受任何参数。

返回值#

useParams 返回一个对象,其中包含当前路由已填充的动态参数,在预渲染期间返回 null。

  • 对象中的每个属性都是一个活动的动态段。
  • 属性名是段的名字,属性值是该段被填充的内容。
  • 属性值将是 string 或 string 数组,具体取决于动态段的类型。
  • 如果路由不包含动态参数,useParams 返回一个空对象。

例如:

路由URLuseParams()
pages/shop/page.js/shop{}
pages/shop/[slug].js/shop/1{ slug: '1' }
pages/shop/[tag]/[item].js/shop/1/2{ tag: '1', item: '2' }
pages/shop/[...slug].js/shop/1/2{ slug: ['1', '2'] }

小知识: useParams 是一个 React Hook,不能与类一起使用。

行为#

预渲染期间的行为#

对于静态优化的页面,useParams 在初始渲染时将返回 null。在水合(hydration)之后,一旦 router 就绪,该值将更新为实际的参数。

这是因为对于动态路由,在静态生成期间无法获知参数。

pages/shop/[slug].tsx
import { useParams } from 'next/navigation'

export default function ShopPage() {
  const params = useParams<{ slug: string }>()

  if (!params) {
    // 当 params 加载时返回后备 UI
    // 这可以防止水合不匹配
    return <ShopPageSkeleton />
  }

  return <>Shop: {params.slug}</>
}
pages/shop/[slug].js
import { useParams } from 'next/navigation'

export default function ShopPage() {
  const params = useParams()

  if (!params) {
    // 当 params 加载时返回后备 UI
    // 这可以防止水合不匹配
    return <ShopPageSkeleton />
  }

  return <>Shop: {params.slug}</>
}

与 getServerSideProps 一起使用#

使用 getServerSideProps 时,页面在每次请求时进行服务端渲染,useParams 会立即返回实际的参数:

pages/shop/[slug].tsx
import { useParams } from 'next/navigation'

export default function ShopPage() {
  const params = useParams<{ slug: string }>()

  // 使用 getServerSideProps 时,这个后备内容永远不会渲染,因为
  // params 在服务器上始终可用。不过,保留
  // 后备内容可以让这个组件在其他页面上复用
  // 这些页面可能不使用 getServerSideProps。
  if (!params) {
    return null
  }

  return <>Shop: {params.slug}</>
}

export async function getServerSideProps() {
  return { props: {} }
}
pages/shop/[slug].js
import { useParams } from 'next/navigation'

export default function ShopPage() {
  const params = useParams()

  // 使用 getServerSideProps 时,这个后备内容永远不会渲染,因为
  // params 在服务器上始终可用。不过,保留
  // 后备内容可以让这个组件在其他页面上复用
  // 这些页面可能不使用 getServerSideProps。
  if (!params) {
    return null
  }

  return <>Shop: {params.slug}</>
}

export async function getServerSideProps() {
  return { props: {} }
}

与 router.query 的比较#

useParams 只返回动态路由参数,而来自 useRouter 的 router.query 同时包含动态参数和查询字符串参数。

pages/shop/[slug].tsx
import { useRouter } from 'next/router'
import { useParams } from 'next/navigation'

export default function ShopPage() {
  const router = useRouter()
  const params = useParams()

  // URL -> /shop/shoes?color=red

  // router.query -> { slug: 'shoes', color: 'red' }
  // params -> { slug: 'shoes' }

  // ...
}
pages/shop/[slug].js
import { useRouter } from 'next/router'
import { useParams } from 'next/navigation'

export default function ShopPage() {
  const router = useRouter()
  const params = useParams()

  // URL -> /shop/shoes?color=red

  // router.query -> { slug: 'shoes', color: 'red' }
  // params -> { slug: 'shoes' }

  // ...
}

示例#

与 App Router 共享组件#

来自 next/navigation 的 useParams 在 Pages Router 和 App Router 中都可用。这使你可以创建在任一环境中都能工作的共享组件:

components/breadcrumb.tsx
import { useParams } from 'next/navigation'

// 此组件在 pages/ 和 app/ 中都可用
export function Breadcrumb() {
  const params = useParams<{ slug: string }>()

  if (!params) {
    // Pages Router 在预渲染期间的后备内容
    return <nav>Home / ...</nav>
  }

  return <nav>Home / {params.slug}</nav>
}
components/breadcrumb.js
import { useParams } from 'next/navigation'

// 此组件在 pages/ 和 app/ 中都可用
export function Breadcrumb() {
  const params = useParams()

  if (!params) {
    // Pages Router 在预渲染期间的后备内容
    return <nav>Home / ...</nav>
  }

  return <nav>Home / {params.slug}</nav>
}

小知识: 在 App Router 中使用此组件时,useParams 永远不会返回 null,因此后备分支不会被渲染。

版本历史#

版本变更
v13.3.0引入 useParams。
Next.js 中文网