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

`useRouter()`

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

注意事項：

請勿將不受信任或未經處理的 URL 傳遞給 router.push 或 router.replace，這可能會導致您的網站暴露於跨站腳本 (XSS) 攻擊。例如，傳遞給 router.push 或 router.replace 的 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 '...'
}

可將此元件導入至佈局 (layout) 中。

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 在導航至新路由時會滾動至頁面頂部。您可以透過向 router.push() 或 router.replace() 傳遞 scroll: false 來禁用此行為。

'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` 遷移