useRouter 钩子允许你在客户端组件中以编程方式更改路由。

推荐： 除非有特定需求使用 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>
  )
}

useRouter()

router.push(href: string, { scroll: boolean }): 执行客户端导航到指定路由，在浏览器的历史记录堆栈中添加新条目。
router.replace(href: string, { scroll: boolean }): 执行客户端导航到指定路由，但不在浏览器的历史记录堆栈中添加新条目。
router.refresh(): 刷新当前路由，向服务器发起新请求，重新获取数据并重新渲染服务端组件。客户端将合并更新的 React 服务端组件内容而不丢失未受影响的客户端 React 状态（如 useState）或浏览器状态（如滚动位置）。
router.prefetch(href: string): 为更快的客户端过渡预取指定路由。
router.back(): 导航回浏览器历史记录堆栈中的上一条路由。
router.forward(): 导航到浏览器历史记录堆栈中的下一页。

值得注意的是：

<Link> 组件在进入视口时会自动预取路由。

如果请求被缓存，refresh() 可能会重新产生相同的结果。其他动态功能，如 cookies 和 headers 也可能改变响应。

从 next/router 迁移

在使用应用路由器时，useRouter 钩子应从 next/navigation 导入，而不是从 next/router 导入。
pathname 字符串已被移除，替代为 usePathname()。
query 对象已被移除，替代为 useSearchParams()。
router.events 已被替代。参见下方。

查看完整迁移指南。

示例

路由事件

你可以通过组合其他客户端组件钩子（如 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 在导航到新路由时会滚动到页面顶部。你可以通过将 scroll: false 传递给 router.push() 或 router.replace() 来禁用此行为。

// 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>
  )
}

版本历史

版本	变更
`v13.0.0`	`useRouter` 从 `next/navigation` 中引入。

使用路由

useRouter()

从 next/router 迁移

示例

路由事件

禁用滚动恢复

版本历史