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返回一个空对象。
例如:
| 路由 | URL | useParams() |
|---|---|---|
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。 |