useRouter

useRouter hook 允许您在客户端组件内部以编程方式更改路由。

建议： 使用 <Link> 组件进行导航，除非您有使用 useRouter 的特定要求。

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

jsx

'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, options?: { onInvalidate?: () => void }): 预取提供的路由，以实现更快的客户端过渡。当预取数据失效时，可选的 onInvalidate 回调会被调用。
router.back(): 导航回浏览器历史堆栈中的上一个路由。
router.forward(): 导航到浏览器历史堆栈中的下一个页面。

须知：

您绝不能向 router.push 或 router.replace 发送不受信任或未经净化的 URL，因为这可能导致您的站点存在跨站脚本 (XSS) 漏洞。例如，发送到 router.push 或 router.replace 的 javascript: URL 将在您的页面上下文中执行。

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

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

onInvalidate 回调每个预取请求最多调用一次。它指示您何时可能需要为更新的路由数据触发新的预取。

从 `next/router` 迁移

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

查看完整的迁移指南。

示例

路由事件

您可以通过组合其他客户端组件 hook，例如 usePathname 和 useSearchParams，来监听页面变化。

jsx

'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)
    // You can now use the current URL
    // ...
  }, [pathname, searchParams])

  return '...'
}

它可以被导入到布局中。

jsx

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() 来禁用此行为。

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

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

版本历史

版本	更改
`v15.4.0`	引入了 `router.prefetch` 的可选 `onInvalidate` 回调
`v13.0.0`	引入了 `next/navigation` 中的 `useRouter`。

useRouter hook 允许您在客户端组件内部以编程方式更改路由。

建议： 使用 <Link> 组件进行导航，除非您有使用 useRouter 的特定要求。

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

jsx

'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, options?: { onInvalidate?: () => void }): 预取提供的路由，以实现更快的客户端过渡。当预取数据失效时，可选的 onInvalidate 回调会被调用。
router.back(): 导航回浏览器历史堆栈中的上一个路由。
router.forward(): 导航到浏览器历史堆栈中的下一个页面。

须知：

您绝不能向 router.push 或 router.replace 发送不受信任或未经净化的 URL，因为这可能导致您的站点存在跨站脚本 (XSS) 漏洞。例如，发送到 router.push 或 router.replace 的 javascript: URL 将在您的页面上下文中执行。

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

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

onInvalidate 回调每个预取请求最多调用一次。它指示您何时可能需要为更新的路由数据触发新的预取。

从 `next/router` 迁移

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

查看完整的迁移指南。

示例

路由事件

您可以通过组合其他客户端组件 hook，例如 usePathname 和 useSearchParams，来监听页面变化。

jsx

'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)
    // You can now use the current URL
    // ...
  }, [pathname, searchParams])

  return '...'
}

它可以被导入到布局中。

jsx

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() 来禁用此行为。

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

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

版本历史

版本	更改
`v15.4.0`	引入了 `router.prefetch` 的可选 `onInvalidate` 回调
`v13.0.0`	引入了 `next/navigation` 中的 `useRouter`。

文档导航

useRouter()

从 next/router 迁移

示例

路由事件

禁用滚动到顶部

版本历史

useRouter()

从 next/router 迁移

示例

路由事件

禁用滚动到顶部

版本历史

`useRouter()`

从 `next/router` 迁移

`useRouter()`

从 `next/router` 迁移