logoNext.js 日本語
ドキュメントブログ学習
はじめに/API リファレンス/関数/useRouter

useRouter

アプリ内の任意の関数コンポーネントで router オブジェクト にアクセスしたい場合、useRouter フックを使用できます。以下の例をご覧ください:

import { useRouter } from 'next/router'

function ActiveLink({ children, href }) {
  const router = useRouter()
  const style = {
    marginRight: 10,
    color: router.asPath === href ? 'red' : 'black',
  }

  const handleClick = (e) => {
    e.preventDefault()
    router.push(href)
  }

  return (
    <a href={href} onClick={handleClick} style={style}>
      {children}
    </a>
  )
}

export default ActiveLink

useRouter は React Hook であるため、クラスと一緒に使用することはできません。withRouter を使用するか、クラスを関数コンポーネントでラップしてください。

router オブジェクト

以下は useRouter と withRouter の両方から返される router オブジェクトの定義です:

  • pathname: String - /pages 以下の現在のルートファイルのパス。したがって、basePath、locale、および末尾のスラッシュ (trailingSlash: true) は含まれません。
  • query: Object - クエリ文字列をオブジェクトにパースしたもの。動的ルート パラメータを含みます。ページが サーバーサイドレンダリング (SSR) を使用していない場合、プリレンダリング中は空のオブジェクトになります。デフォルトは {}
  • asPath: String - ブラウザに表示されるパスで、検索パラメータを含み、trailingSlash 設定を尊重します。basePath と locale は含まれません。
  • isFallback: boolean - 現在のページが フォールバックモード かどうか。
  • basePath: String - アクティブな basePath (有効な場合)。
  • locale: String - アクティブなロケール (有効な場合)。
  • locales: String[] - サポートされているすべてのロケール (有効な場合)。
  • defaultLocale: String - 現在のデフォルトロケール (有効な場合)。
  • domainLocales: Array<{domain, defaultLocale, locales}> - 設定されたドメインロケール。
  • isReady: boolean - ルーターフィールドがクライアントサイドで更新され、使用準備ができているかどうか。useEffect メソッド内でのみ使用し、サーバーでの条件付きレンダリングには使用しないでください。関連ドキュメント: 自動静的最適化ページ
  • isPreview: boolean - アプリケーションが現在 プレビューモード かどうか。

asPath フィールドを使用すると、ページがサーバーサイドレンダリングまたは 自動静的最適化 を使用してレンダリングされている場合、クライアントとサーバー間の不一致が発生する可能性があります。isReady フィールドが true になるまで asPath の使用を避けてください。

router には以下のメソッドが含まれています:

router.push

クライアントサイドの遷移を処理します。このメソッドは next/link では不十分な場合に便利です。

router.push(url, as, options)
  • url: UrlObject | String - ナビゲート先の URL (UrlObject プロパティについては Node.JS URL モジュールドキュメント を参照)。
  • as: UrlObject | String - ブラウザの URL バーに表示されるパスのオプションデコレータ。Next.js 9.5.3 より前では動的ルートに使用されていました。
  • options - 以下の設定オプションを持つオプションオブジェクト:
    • scroll - オプションのブール値で、ナビゲーション後にページの先頭にスクロールするかどうかを制御します。デフォルトは true
    • shallow: getStaticProps、getServerSideProps、getInitialProps を再実行せずに現在のページのパスを更新します。デフォルトは false
    • locale - オプションの文字列で、新しいページのロケールを示します

外部 URL には router.push を使用する必要はありません。そのような場合は window.location が適しています。

事前定義されたルートである pages/about.js にナビゲートする例:

import { useRouter } from 'next/router'

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

  return (
    <button type="button" onClick={() => router.push('/about')}>
      Click me
    </button>
  )
}

動的ルートである pages/post/[pid].js にナビゲートする例:

import { useRouter } from 'next/router'

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

  return (
    <button type="button" onClick={() => router.push('/post/abc')}>
      Click me
    </button>
  )
}

認証 の背後にあるページにユーザーをリダイレクトする例 (pages/login.js):

import { useEffect } from 'react'
import { useRouter } from 'next/router'

// ここでユーザーを取得して返す
const useUser = () => ({ user: null, loading: false })

export default function Page() {
  const { user, loading } = useUser()
  const router = useRouter()

  useEffect(() => {
    if (!(user || loading)) {
      router.push('/login')
    }
  }, [user, loading])

  return <p>Redirecting...</p>
}

ナビゲーション後の状態リセット

Next.js で同じページにナビゲートする場合、親コンポーネントが変更されない限り、React はアンマウントしないため、ページの状態はデフォルトで リセットされません。

pages/[slug].js
import Link from 'next/link'
import { useState } from 'react'
import { useRouter } from 'next/router'

export default function Page(props) {
  const router = useRouter()
  const [count, setCount] = useState(0)
  return (
    <div>
      <h1>Page: {router.query.slug}</h1>
      <p>Count: {count}</p>
      <button onClick={() => setCount(count + 1)}>Increase count</button>
      <Link href="/one">one</Link> <Link href="/two">two</Link>
    </div>
  )
}

上記の例では、/one と /two 間のナビゲートでカウントは リセットされません。トップレベルの React コンポーネント Page が同じであるため、useState はレンダリング間で維持されます。

この動作を望まない場合、いくつかのオプションがあります:

  • useEffect を使用して各状態を手動で更新します。上記の例では次のようになります:

    useEffect(() => {
  setCount(0)
}, [router.query.slug])

  • React の key を使用して React にコンポーネントを再マウントさせる。すべてのページに対してこれを行うには、カスタムアプリを使用します:

    pages/_app.js
    import { useRouter } from 'next/router'

export default function MyApp({ Component, pageProps }) {
  const router = useRouter()
  return <Component key={router.asPath} {...pageProps} />
}

URL オブジェクトの使用

next/link と同様に URL オブジェクトを使用できます。url と as パラメータの両方で動作します:

import { useRouter } from 'next/router'

export default function ReadMore({ post }) {
  const router = useRouter()

  return (
    <button
      type="button"
      onClick={() => {
        router.push({
          pathname: '/post/[pid]',
          query: { pid: post.id },
        })
      }}
    >
      Click here to read more
    </button>
  )
}

router.replace

next/link の replace プロパティと同様に、router.replace は history スタックに新しい URL エントリを追加しません。

router.replace(url, as, options)
  • router.replace の API は router.push とまったく同じです。

以下の例をご覧ください:

import { useRouter } from 'next/router'

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

  return (
    <button type="button" onClick={() => router.replace('/home')}>
      Click me
    </button>
  )
}

router.prefetch

クライアントサイドの遷移を高速化するためにページをプリフェッチします。このメソッドは next/link を使用しないナビゲーションにのみ有用です。next/link はページのプリフェッチを自動的に処理します。

これは本番環境のみの機能です。Next.js は開発環境ではページをプリフェッチしません。

router.prefetch(url, as, options)
  • url - プリフェッチする URL。明示的なルート (例: /dashboard) と動的ルート (例: /product/[id]) を含みます。
  • as - url のオプションデコレータ。Next.js 9.5.3 より前では動的ルートのプリフェッチに使用されていました。
  • options - 以下の許可されたフィールドを持つオプションオブジェクト:
    • locale - アクティブなロケールとは異なるロケールを提供できます。false の場合、url にはアクティブロケールが使用されないため、ロケールを含める必要があります。

ログインページがあり、ログイン後にユーザーをダッシュボードにリダイレクトする場合を考えます。その場合、以下の例のようにダッシュボードをプリフェッチして遷移を高速化できます:

import { useCallback, useEffect } from 'react'
import { useRouter } from 'next/router'

export default function Login() {
  const router = useRouter()
  const handleSubmit = useCallback((e) => {
    e.preventDefault()

    fetch('/api/login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        /* フォームデータ */
      }),
    }).then((res) => {
      // すでにプリフェッチされたダッシュボードページに高速クライアントサイド遷移
      if (res.ok) router.push('/dashboard')
    })
  }, [])

  useEffect(() => {
    // ダッシュボードページをプリフェッチ
    router.prefetch('/dashboard')
  }, [router])

  return (
    <form onSubmit={handleSubmit}>
      {/* フォームフィールド */}
      <button type="submit">Login</button>
    </form>
  )
}

router.beforePopState

カスタムサーバー を使用している場合など、popstate をリッスンし、ルーターが処理する前に何かを行いたいことがあります。

router.beforePopState(cb)
  • cb - 受信 popstate イベントで実行する関数。この関数は以下のプロパティを持つオブジェクトとしてイベントの状態を受け取ります:
    • url: String - 新しい状態のルート。通常は page の名前です
    • as: String - ブラウザに表示される URL
    • options: Object - router.push から送信された追加オプション

cb が false を返す場合、Next.js ルーターは popstate を処理せず、その場合は自分で処理する必要があります。ファイルシステムルーティングの無効化 を参照してください。

beforePopState を使用してリクエストを操作したり、SSR リフレッシュを強制したりできます。以下の例をご覧ください:

import { useEffect } from 'react'
import { useRouter } from 'next/router'

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

  useEffect(() => {
    router.beforePopState(({ url, as, options }) => {
      // これらの2つのルートのみを許可したい！
      if (as !== '/' && as !== '/other') {
        // SSR で不正なルートを404としてレンダリング
        window.location.href = as
        return false
      }

      return true
    })
  }, [router])

  return <p>Welcome to the page</p>
}

router.back

履歴を戻ります。ブラウザの戻るボタンをクリックするのと同じです。window.history.back() を実行します。

import { useRouter } from 'next/router'

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

  return (
    <button type="button" onClick={() => router.back()}>
      Click here to go back
    </button>
  )
}

router.reload

現在の URL を再読み込みします。ブラウザの更新ボタンをクリックするのと同じです。window.location.reload() を実行します。

import { useRouter } from 'next/router'

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

  return (
    <button type="button" onClick={() => router.reload()}>
      Click here to reload
    </button>
  )
}

router.events

Next.js Router 内で発生するさまざまなイベントをリッスンできます。以下はサポートされているイベントのリストです:

  • routeChangeStart(url, { shallow }) - ルートの変更が開始されたときに発火
  • routeChangeComplete(url, { shallow }) - ルートの変更が完全に完了したときに発火
  • routeChangeError(err, url, { shallow }) - ルート変更中にエラーが発生した場合、またはルートの読み込みがキャンセルされたときに発火
    • err.cancelled - ナビゲーションがキャンセルされたかどうかを示す
  • beforeHistoryChange(url, { shallow }) - ブラウザの履歴を変更する前に発火
  • hashChangeStart(url, { shallow }) - ハッシュが変更されようとしているが、ページは変更されないときに発火
  • hashChangeComplete(url, { shallow }) - ハッシュが変更されたが、ページは変更されなかったときに発火

知っておくと良いこと: ここでの url は basePath を含むブラウザに表示される URL です。

例えば、ルーターイベント routeChangeStart をリッスンするには、pages/_app.js を開くか作成し、以下のようにイベントを購読します:

import { useEffect } from 'react'
import { useRouter } from 'next/router'

export default function MyApp({ Component, pageProps }) {
  const router = useRouter()

  useEffect(() => {
    const handleRouteChange = (url, { shallow }) => {
      console.log(
        `App is changing to ${url} ${
          shallow ? 'with' : 'without'
        } shallow routing`
      )
    }

    router.events.on('routeChangeStart', handleRouteChange)

    // コンポーネントがアンマウントされたら、
    // 'off' メソッドでイベントの購読を解除:
    return () => {
      router.events.off('routeChangeStart', handleRouteChange)
    }
  }, [router])

  return <Component {...pageProps} />
}

この例では カスタム App (pages/_app.js) を使用しています。これはページナビゲーションでアンマウントされないためですが、アプリケーション内の任意のコンポーネントでルーターイベントを購読できます。

ルーターイベントは、コンポーネントがマウントされたとき (useEffect または componentDidMount / componentWillUnmount) に登録するか、イベントが発生したときに命令的に登録する必要があります。

ルートの読み込みがキャンセルされた場合 (例えば、2つのリンクを連続して素早くクリックした場合)、routeChangeError が発火します。渡される err には cancelled プロパティが true に設定されます。以下の例をご覧ください:

import { useEffect } from 'react'
import { useRouter } from 'next/router'

export default function MyApp({ Component, pageProps }) {
  const router = useRouter()

  useEffect(() => {
    const handleRouteChangeError = (err, url) => {
      if (err.cancelled) {
        console.log(`Route to ${url} was cancelled!`)
      }
    }

    router.events.on('routeChangeError', handleRouteChangeError)

    // コンポーネントがアンマウントされたら、
    // 'off' メソッドでイベントの購読を解除:
    return () => {
      router.events.off('routeChangeError', handleRouteChangeError)
    }
  }, [router])

  return <Component {...pageProps} />
}

next/compat/router エクスポート

これは同じ useRouter フックですが、app ディレクトリと pages ディレクトリの両方で使用できます。

next/router との違いは、ページルーターがマウントされていない場合にエラーをスローせず、代わりに NextRouter | null という戻り値の型を持つことです。 これにより、開発者は app ルーターへの移行中に、コンポーネントを app と pages の両方で動作するように変換できます。

以前は次のようになっていたコンポーネント:

import { useRouter } from 'next/router'
const MyComponent = () => {
  const { isReady, query } = useRouter()
  // ...
}

next/compat/router に変換すると、null を分割代入できないためエラーが発生します。代わりに、開発者は新しいフックを活用できます:

import { useEffect } from 'react'
import { useRouter } from 'next/compat/router'
import { useSearchParams } from 'next/navigation'
const MyComponent = () => {
  const router = useRouter() // null または NextRouter インスタンスの可能性あり
  const searchParams = useSearchParams()
  useEffect(() => {
    if (router && !router.isReady) {
      return
    }
    // `app/` では searchParams は即座に値とともに準備完了、
    // `pages/` ではルーターが準備完了後に利用可能
    const search = searchParams.get('search')
    // ...
  }, [router, searchParams])
  // ...
}

このコンポーネントは pages と app ディレクトリの両方で動作します。コンポーネントが pages で使用されなくなったら、compat ルーターへの参照を削除できます:

import { useSearchParams } from 'next/navigation'
const MyComponent = () => {
  const searchParams = useSearchParams()
  // このコンポーネントが `app/` のみで使用されるため、compat ルーターは削除可能
  const search = searchParams.get('search')
  // ...
}

pages ディレクトリでの Next.js コンテキスト外での useRouter 使用

もう1つの特定のユースケースは、pages ディレクトリ内の getServerSideProps 内など、Next.js アプリケーションコンテキスト外でコンポーネントをレンダリングする場合です。この場合、compat ルーターを使用してエラーを回避できます:

import { renderToString } from 'react-dom/server'
import { useRouter } from 'next/compat/router'
const MyComponent = () => {
  const router = useRouter() // null または NextRouter インスタンスの可能性あり
  // ...
}
export async function getServerSideProps() {
  const renderedComponent = renderToString(<MyComponent />)
  return {
    props: {
      renderedComponent,
    },
  }
}

ESLint の潜在的なエラー

router オブジェクトでアクセス可能な特定のメソッドは Promise を返します。no-floating-promises ESLint ルールが有効な場合、グローバルに、または該当行のみで無効にすることを検討してください。

アプリケーションでこのルールが必要な場合は、Promise を void にするか、async 関数を使用して Promise を await し、関数呼び出しを void にします。この方法は onClick ハンドラー内からメソッドが呼び出される場合には適用されません。

影響を受けるメソッド:

  • router.push
  • router.replace
  • router.prefetch

潜在的な解決策

import { useEffect } from 'react'
import { useRouter } from 'next/router'

// ここでユーザーを取得して返す
const useUser = () => ({ user: null, loading: false })

export default function Page() {
  const { user, loading } = useUser()
  const router = useRouter()

  useEffect(() => {
    // 次の行のリンターを無効化 - これが最もクリーンな解決策
    // eslint-disable-next-line no-floating-promises
    router.push('/login')

    // router.push が返す Promise を void にする
    if (!(user || loading)) {
      void router.push('/login')
    }
    // または async 関数を使用し、Promise を await して関数呼び出しを void にする
    async function handleRouteChange() {
      if (!(user || loading)) {
        await router.push('/login')
      }
    }
    void handleRouteChange()
  }, [user, loading])

  return <p>リダイレクト中...</p>
}

withRouter

useRouter が最適でない場合、withRouter を使用して同じ router オブジェクト を任意のコンポーネントに追加できます。

使用方法

import { withRouter } from 'next/router'

function Page({ router }) {
  return <p>{router.pathname}</p>
}

export default withRouter(Page)

TypeScript

クラスコンポーネントで withRouter を使用する場合、コンポーネントは router プロップを受け入れる必要があります:

import React from 'react'
import { withRouter, NextRouter } from 'next/router'

interface WithRouterProps {
  router: NextRouter
}

interface MyComponentProps extends WithRouterProps {}

class MyComponent extends React.Component<MyComponentProps> {
  render() {
    return <p>{this.props.router.pathname}</p>
  }
}

export default withRouter(MyComponent)

useReportWebVitals

useReportWebVitals フック

userAgent

userAgent ヘルパーは、Web Request API を拡張し、リクエストからユーザーエージェントオブジェクトを操作するための追加プロパティとメソッドを提供します。