useRouter

useRouter 鉤子允許您在客戶端組件 (Client Components) 中透過程式化方式變更路由。

建議： 除非有特殊需求需要使用 useRouter，否則請使用 <Link> 組件進行導航。

'use client'

import { useRouter } from 'next/navigation'

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

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

'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 }): 執行客戶端導航至指定路由。會在瀏覽器歷史記錄 (browser’s history) 堆疊中新增一筆記錄。
router.replace(href: string, { scroll: boolean }): 執行客戶端導航至指定路由，但不會在瀏覽器歷史記錄堆疊 (browser’s history stack) 中新增記錄。
router.refresh(): 重新整理當前路由。會向伺服器發送新請求，重新獲取資料並重新渲染伺服器組件。客戶端會合併更新後的 React 伺服器組件負載，而不會遺失未受影響的客戶端 React 狀態（如 useState）或瀏覽器狀態（如滾動位置）。
router.prefetch(href: string): 預取 (Prefetch) 指定路由以實現更快的客戶端轉場。
router.back(): 導航回瀏覽器歷史記錄堆疊中的上一頁。
router.forward(): 導航至瀏覽器歷史記錄堆疊中的下一頁。

須知事項:

請勿將未受信任或未經消毒的 URL 傳遞給 router.push 或 router.replace，這可能導致您的網站暴露於跨站腳本 (XSS) 攻擊。例如，傳遞 javascript: URL 將會在您的頁面上下文中執行。

<Link> 組件會在路由進入視窗可見範圍時自動預取。

如果 fetch 請求被快取，refresh() 可能會產生相同的結果。其他動態 API 如 cookies 和 headers 也可能改變回應。

從 `next/router` 遷移

使用 App 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() 在靜態渲染 (static rendering) 期間會導致客戶端渲染直到最近的 Suspense 邊界。了解更多。

禁用滾動至頂部

預設情況下，Next.js 在導航至新路由時會滾動至頁面頂部。您可以通過傳遞 scroll: false 給 router.push() 或 router.replace() 來禁用此行為。

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

'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`	從 `next/navigation` 導入的 `useRouter` 被引入

useRouter()

從 next/router 遷移

範例

路由器事件

禁用滾動至頂部

版本歷史

On this page

`useRouter()`

從 `next/router` 遷移