NNext.js 中文网 GitHub

useRouter

useRouter hook 的 API 参考。

useRouter hook 让你可以在 Client Component 中以编程方式更改路由。

建议: 除非你对使用 useRouter 有特定需求,否则请使用 <Link> 组件进行导航。

app/example-client-component.tsx
'use client'

import { useRouter } from 'next/navigation'

export default function Page() {
  const router = useRouter()

  return (
    <button type="button" onClick={() => router.push('/dashboard')}>
      Dashboard
    </button>
  )
}
app/example-client-component.js
'use client'

import { useRouter } from 'next/navigation'

export default function Page() {
  const router = useRouter()

  return (
    <button type="button" onClick={() => router.push('/dashboard')}>
      Dashboard
    </button>
  )
}

useRouter()#

router.push()#

ts
router.push(href: string, {
  scroll: boolean
  transitionTypes: string[]
})

执行到所提供路由的客户端导航。在浏览器的历史记录栈中添加一个新条目。可选的 transitionTypes 会在导航 Transition 中传递给 React.addTransitionType。

router.replace()#

ts
router.replace(href: string, {
  scroll: boolean
  transitionTypes: string[]
})

执行到所提供路由的客户端导航,但不在浏览器的历史记录栈中添加新条目。可选的 transitionTypes 会在导航 Transition 中传递给 React.addTransitionType。

router.refresh()#

ts
router.refresh()

刷新当前路由。向服务端发出新请求,重新获取数据请求,并重新渲染 Server Component。客户端会合并更新后的 React Server Component payload,而不会丢失未受影响的客户端 React 状态(例如 useState)或浏览器状态(例如滚动位置)。这会清除当前路由的客户端缓存,但不会使服务端缓存失效。请使用 revalidatePath 或 revalidateTag 来使服务端缓存的数据失效。

router.prefetch()#

ts
router.prefetch(
  href: string,
  options?: {
    kind?: 'auto' | 'full'
    onInvalidate?: () => void
  }
)

预取所提供的路由,以加快客户端过渡速度。可选的 kind 控制预取路由的程度。可选的 onInvalidate 回调会在预取数据变得陈旧时被调用。

借助 Partial Prefetching,每次 router.prefetch() 调用都对应一个 <Link> 预取选项:

<div style={{ overflowX: 'auto', width: '100%' }}>

router.prefetch() 调用等效的 <Link>
router.prefetch(href)<Link href={href}>
router.prefetch(href, { kind: 'auto' })<Link href={href}>
router.prefetch(href, { kind: 'full' })<Link href={href} prefetch={true}>

</div>

默认选项和 'auto' 选项会预取路由的 App Shell。'full' 选项还会预取逐链接阶段,包括 await prefetch() 下方的内容。

这两个选项都不包含通过 await navigation() 推迟的内容。该内容会在导航开始时渲染。

router.back()#

ts
router.back()

导航回浏览器历史记录栈中的上一个路由。

router.forward()#

ts
router.forward()

向前导航到浏览器历史记录栈中的下一个页面。

router.back() 和 router.forward() 不会触发视图过渡动画。请参阅浏览器历史记录导航期间的视图过渡。

router.bfcacheId#

一个作用于当前路由段的不透明字符串标识符。当周围段因 push 或 replace 导航而被重新创建时,它会发生变化;对于前进/后退导航、router.refresh() 以及仅涉及搜索参数或 hash 的导航,它保持不变。详情请参阅下文的 bfcacheId。

小知识:

  • 你不得将不受信任或未经过清理的 URL 传给 router.push 或 router.replace,因为这会让你的网站遭受跨站脚本(XSS)漏洞攻击。例如,传给 router.push 或 router.replace 的 javascript: URL 会在你的页面上下文中执行。
  • <Link> 组件会在路由进入视口时自动预取它们。
  • 如果 fetch 请求被缓存,refresh() 可能会重新产生相同的结果。其他请求时 API(例如 cookies 和 headers)也可能改变响应。
  • onInvalidate 回调每次预取请求最多调用一次。它表明你可能希望在何时触发一次新的预取以获取更新后的路由数据。

从 next/router 迁移#

  • 使用 App Router 时,useRouter hook 应从 next/navigation 导入,而不是 next/router。
  • pathname 字符串已被移除,由 usePathname() 取代。
  • query 对象已被移除,由 useSearchParams() 取代。
  • router.events 已被替换。见下文。

查看完整的迁移指南。

示例#

Router 事件#

你可以通过组合其他 Client Component hook(例如 usePathname 和 useSearchParams)来监听页面变化。

app/components/navigation-events.js
'use client'

import { useEffect } from 'react'
import { usePathname, useSearchParams } from 'next/navigation'

export function NavigationEvents() {
  const pathname = usePathname()
  const searchParams = useSearchParams()

  useEffect(() => {
    const url = `${pathname}?${searchParams}`
    console.log(url)
    // 现在你可以使用当前 URL
    // ...
  }, [pathname, searchParams])

  return '...'
}

它可以被导入到布局中。

app/layout.js
import { Suspense } from 'react'
import { NavigationEvents } from './components/navigation-events'

export default function Layout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}

        <Suspense fallback={null}>
          <NavigationEvents />
        </Suspense>
      </body>
    </html>
  )
}

小知识:<NavigationEvents> 被包裹在 Suspense 边界中,因为useSearchParams() 会在预渲染期间导致客户端渲染一直延伸到最近的 Suspense 边界。了解更多。

禁用滚动到顶部#

默认情况下,当导航到新路由时,Next.js 会滚动到页面顶部。你可以通过向 router.push() 或 router.replace() 传递 scroll: false 来禁用此行为。

app/example-client-component.tsx
'use client'

import { useRouter } from 'next/navigation'

export default function Page() {
  const router = useRouter()

  return (
    <button
      type="button"
      onClick={() => router.push('/dashboard', { scroll: false })}
    >
      Dashboard
    </button>
  )
}
app/example-client-component.jsx
'use client'

import { useRouter } from 'next/navigation'

export default function Page() {
  const router = useRouter()

  return (
    <button
      type="button"
      onClick={() => router.push('/dashboard', { scroll: false })}
    >
      Dashboard
    </button>
  )
}

bfcacheId#

router.bfcacheId 是一个作用于当前路由段的不透明字符串标识符。当周围段因 push 或 replace 导航而被重新创建时,它会发生变化;对于前进/后退导航、router.refresh() 以及仅涉及搜索参数或 hash 的导航,它保持不变。

推荐的用法是将其作为 React key 传入,以在新的导航中退出状态保持,同时在前进/后退导航期间仍然恢复状态:

app/example/page.tsx
'use client'

import { useRouter } from 'next/navigation'

export default function Page() {
  const { bfcacheId } = useRouter()
  return <form key={bfcacheId}></form>
}

当启用 cacheComponents 时,App Router 会使用 React <Activity> 在导航之间保持 Client Component 的状态。以 bfcacheId 作为组件 key 会在每次新的导航时重置它,同时仍在浏览器前进/后退导航之间保持其状态。有关推荐的按模式重置方法,请参阅保持 UI 状态。

小知识:除了 bfcacheId,更推荐在事件处理器(例如 onSubmit)中显式重置状态,或从你的数据中派生一个 key(例如来自服务端的草稿 id)。仅在万不得已时才使用 bfcacheId,例如迁移现有代码库时。

版本历史#

版本变更
v16.5.0引入 router.prefetch 的 kind 选项。
v15.4.0引入 router.prefetch 的可选 onInvalidate 回调
v13.0.0引入来自 next/navigation 的 useRouter。
Next.js 中文网