useRouter

Wenn Sie auf das router-Objekt innerhalb einer beliebigen Funktionskomponente Ihrer Anwendung zugreifen möchten, können Sie den useRouter-Hook verwenden. Sehen Sie sich das folgende Beispiel an:

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 ist ein React Hook, was bedeutet, dass er nicht mit Klassen verwendet werden kann. Sie können entweder withRouter verwenden oder Ihre Klasse in eine Funktionskomponente einbinden.

`router`-Objekt

Folgend ist die Definition des router-Objekts, das sowohl von useRouter als auch von withRouter zurückgegeben wird:

pathname: String - Der Pfad der aktuellen Routendatei nach /pages. Daher sind basePath, locale und der abschließende Schrägstrich (trailingSlash: true) nicht enthalten.
query: Object - Die als Objekt geparste Abfragezeichenfolge, einschließlich der Parameter für dynamische Routen. Während des Prerenderings ist es ein leeres Objekt, wenn die Seite kein Server-seitiges Rendering (SSR) verwendet. Standardwert ist {}.
asPath: String - Der im Browser angezeigte Pfad einschließlich der Suchparameter und unter Berücksichtigung der trailingSlash-Konfiguration. basePath und locale sind nicht enthalten.
isFallback: boolean - Gibt an, ob sich die aktuelle Seite im Fallback-Modus befindet.
basePath: String - Der aktive basePath (falls aktiviert).
locale: String - Die aktive Locale (falls aktiviert).
locales: String[] - Alle unterstützten Locales (falls aktiviert).
defaultLocale: String - Die aktuelle Standard-Locale (falls aktiviert).
domainLocales: Array<{domain, defaultLocale, locales}> - Alle konfigurierten Domain-Locales.
isReady: boolean - Gibt an, ob die Router-Felder clientseitig aktualisiert und einsatzbereit sind. Sollte nur innerhalb von useEffect-Methoden verwendet werden und nicht für bedingtes Rendering auf dem Server. Siehe verwandte Dokumentation für den Anwendungsfall mit automatisch statisch optimierten Seiten.
isPreview: boolean - Gibt an, ob sich die Anwendung aktuell im Vorschaumodus (Preview Mode) befindet.

Die Verwendung des asPath-Felds kann zu einer Diskrepanz zwischen Client und Server führen, wenn die Seite mit Server-seitigem Rendering oder automatischer statischer Optimierung (Automatic Static Optimization) gerendert wird. Vermeiden Sie die Verwendung von asPath, bis das isReady-Feld true ist.

Die folgenden Methoden sind im router-Objekt enthalten:

router.push

Beispiele

Router verwenden

Behandelt clientseitige Übergänge. Diese Methode ist nützlich für Fälle, in denen next/link nicht ausreicht.

router.push(url, as, options)

url: UrlObject | String - Die URL, zu der navigiert werden soll (siehe Node.JS URL-Modul-Dokumentation für UrlObject-Eigenschaften).
as: UrlObject | String - Optionaler Dekorator für den Pfad, der in der Browser-URL-Leiste angezeigt wird. Vor Next.js 9.5.3 wurde dies für dynamische Routen verwendet.
options - Optionales Objekt mit folgenden Konfigurationsoptionen:
- scroll - Optionaler Boolean, steuert das Scrollen zum Seitenanfang nach der Navigation. Standardwert ist true.
- shallow: Aktualisiert den Pfad der aktuellen Seite, ohne getStaticProps, getServerSideProps oder getInitialProps erneut auszuführen. Standardwert ist false.
- locale - Optionaler String, gibt die Locale der neuen Seite an.

Für externe URLs müssen Sie router.push nicht verwenden. window.location ist dafür besser geeignet.

Navigation zu pages/about.js, einer vordefinierten Route:

import { useRouter } from 'next/router'

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

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

Navigation zu pages/post/[pid].js, einer dynamischen Route:

import { useRouter } from 'next/router'

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

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

Weiterleitung des Benutzers zu pages/login.js, nützlich für Seiten hinter einer Authentifizierung:

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

// Hier würden Sie den Benutzer abfragen und zurückgeben
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>Weiterleitung...</p>
}

Bei der Navigation zur gleichen Seite in Next.js wird der Seitenzustand standardmäßig nicht zurückgesetzt, da React die Komponente nicht aushängt, es sei denn, die übergeordnete Komponente hat sich geändert.

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>Seite: {router.query.slug}</h1>
      <p>Zähler: {count}</p>
      <button onClick={() => setCount(count + 1)}>Zähler erhöhen</button>
      <Link href="/one">eins</Link> <Link href="/two">zwei</Link>
    </div>
  )
}

Im obigen Beispiel wird der Zähler beim Wechsel zwischen /one und /two nicht zurückgesetzt. Der useState-Wert bleibt zwischen den Renderings erhalten, da die übergeordnete React-Komponente Page dieselbe ist.

Wenn Sie dieses Verhalten nicht wünschen, haben Sie mehrere Möglichkeiten:

Manuelles Aktualisieren jedes Zustands mit useEffect. Im obigen Beispiel könnte das so aussehen:
```
useEffect(() => {
  setCount(0)
}, [router.query.slug])
```

Verwenden Sie einen React key, um React mitzuteilen, dass die Komponente neu gemountet werden soll. Um dies für alle Seiten zu tun, können Sie eine benutzerdefinierte App verwenden:

pages/_app.js

import { useRouter } from 'next/router'

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

Mit URL-Objekt

Sie können ein URL-Objekt auf die gleiche Weise verwenden wie für next/link. Funktioniert sowohl für den url- als auch den as-Parameter:

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 },
        })
      }}
    >
      Klicken Sie hier, um mehr zu lesen
    </button>
  )
}

router.replace

Ähnlich wie die replace-Prop in next/link, verhindert router.replace, dass ein neuer URL-Eintrag in den history-Stack hinzugefügt wird.

router.replace(url, as, options)

Die API für router.replace ist genau dieselbe wie die API für router.push.

Sehen Sie sich das folgende Beispiel an:

import { useRouter } from 'next/router'

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

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

router.prefetch

Seiten vorab laden für schnellere clientseitige Übergänge. Diese Methode ist nur für Navigationen ohne next/link nützlich, da next/link das Vorabladen von Seiten automatisch übernimmt.

Dies ist eine Produktionsfunktion. Next.js lädt Seiten im Entwicklungsmodus nicht vorab.

router.prefetch(url, as, options)

url - Die vorabzuladende URL, einschließlich expliziter Routen (z.B. /dashboard) und dynamischer Routen (z.B. /product/[id]).
as - Optionaler Dekorator für url. Vor Next.js 9.5.3 wurde dies verwendet, um dynamische Routen vorabzuladen.
options - Optionales Objekt mit folgenden erlaubten Feldern:
- locale - Ermöglicht die Angabe einer anderen Locale als der aktiven. Wenn false, muss url die Locale enthalten, da die aktive Locale nicht verwendet wird.

Angenommen, Sie haben eine Login-Seite, und nach dem Login leiten Sie den Benutzer zum Dashboard weiter. Für diesen Fall können wir das Dashboard vorab laden, um einen schnelleren Übergang zu ermöglichen, wie im folgenden Beispiel:

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({
        /* Formulardaten */
      }),
    }).then((res) => {
      // Schneller clientseitiger Übergang zur bereits vorab geladenen Dashboard-Seite
      if (res.ok) router.push('/dashboard')
    })
  }, [])

  useEffect(() => {
    // Dashboard-Seite vorab laden
    router.prefetch('/dashboard')
  }, [router])

  return (
    <form onSubmit={handleSubmit}>
      {/* Formularfelder */}
      <button type="submit">Login</button>
    </form>
  )
}

router.beforePopState

In einigen Fällen (z.B. bei Verwendung eines Custom Servers) möchten Sie möglicherweise auf popstate hören und etwas tun, bevor der Router darauf reagiert.

router.beforePopState(cb)

cb - Die Funktion, die bei eingehenden popstate-Ereignissen ausgeführt werden soll. Die Funktion erhält den Zustand des Ereignisses als Objekt mit folgenden Props:
- url: String - Die Route für den neuen Zustand. Dies ist normalerweise der Name einer page.
- as: String - Die URL, die im Browser angezeigt wird.
- options: Object - Zusätzliche Optionen, die von router.push gesendet werden.

Wenn cb false zurückgibt, wird der Next.js-Router popstate nicht behandeln, und Sie sind dafür verantwortlich, es in diesem Fall zu behandeln. Siehe Deaktivieren des Dateisystem-Routings.

Sie können beforePopState verwenden, um die Anfrage zu manipulieren oder ein SSR-Refresh zu erzwingen, wie im folgenden Beispiel:

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

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

  useEffect(() => {
    router.beforePopState(({ url, as, options }) => {
      // Ich möchte nur diese beiden Routen erlauben!
      if (as !== '/' && as !== '/other') {
        // SSR soll ungültige Routen als 404 rendern.
        window.location.href = as
        return false
      }

      return true
    })
  }, [router])

  return <p>Willkommen auf der Seite</p>
}

router.back

Navigiert in der Historie zurück. Entspricht dem Klicken auf die Zurück-Schaltfläche des Browsers. Führt window.history.back() aus.

import { useRouter } from 'next/router'

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

  return (
    <button type="button" onClick={() => router.back()}>
      Klicken Sie hier, um zurückzugehen
    </button>
  )
}

router.reload

Lädt die aktuelle URL neu. Entspricht dem Klicken auf die Aktualisieren-Schaltfläche des Browsers. Führt window.location.reload() aus.

import { useRouter } from 'next/router'

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

  return (
    <button type="button" onClick={() => router.reload()}>
      Klicken Sie hier, um neu zu laden
    </button>
  )
}

router.events

Beispiele

Mit einem Ladeindikator für Seiten

Sie können verschiedene Ereignisse im Next.js-Router abhören. Hier ist eine Liste der unterstützten Ereignisse:

routeChangeStart(url, { shallow }) - Wird ausgelöst, wenn eine Route beginnt, sich zu ändern.
routeChangeComplete(url, { shallow }) - Wird ausgelöst, wenn eine Route vollständig geändert wurde.
routeChangeError(err, url, { shallow }) - Wird ausgelöst, wenn ein Fehler beim Ändern der Routen auftritt oder ein Routenladen abgebrochen wird.
- err.cancelled - Gibt an, ob die Navigation abgebrochen wurde.
beforeHistoryChange(url, { shallow }) - Wird ausgelöst, bevor die Browser-Historie geändert wird.
hashChangeStart(url, { shallow }) - Wird ausgelöst, wenn sich der Hash ändert, aber nicht die Seite.
hashChangeComplete(url, { shallow }) - Wird ausgelöst, wenn sich der Hash geändert hat, aber nicht die Seite.

Wichtig: Hier ist url die im Browser angezeigte URL, einschließlich des basePath.

Um beispielsweise auf das Router-Ereignis routeChangeStart zu hören, öffnen oder erstellen Sie pages/_app.js und abonnieren Sie das Ereignis wie folgt:

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 wechselt zu ${url} ${
          shallow ? 'mit' : 'ohne'
        } shallow routing`
      )
    }

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

    // Wenn die Komponente ausgehängt wird, vom Ereignis
    // mit der `off`-Methode abmelden:
    return () => {
      router.events.off('routeChangeStart', handleRouteChange)
    }
  }, [router])

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

Wir verwenden eine Custom App (pages/_app.js) für dieses Beispiel, um das Ereignis zu abonnieren, weil sie bei Seitenwechseln nicht ausgehängt wird. Sie können Router-Ereignisse jedoch in jeder Komponente Ihrer Anwendung abonnieren.

Router-Ereignisse sollten registriert werden, wenn eine Komponente gemountet wird (useEffect oder componentDidMount / componentWillUnmount) oder imperativ, wenn ein Ereignis eintritt.

Wenn ein Routenladen abgebrochen wird (z.B. durch schnelles Klicken auf zwei Links hintereinander), wird routeChangeError ausgelöst. Das übergebene err enthält eine cancelled-Eigenschaft, die auf true gesetzt ist, wie im folgenden Beispiel:

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 zu ${url} wurde abgebrochen!`)
      }
    }

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

    // Wenn die Komponente ausgehängt wird, vom Ereignis
    // mit der `off`-Methode abmelden:
    return () => {
      router.events.off('routeChangeError', handleRouteChangeError)
    }
  }, [router])

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

Potenzielle ESLint-Fehler

Bestimmte Methoden, die auf dem router-Objekt verfügbar sind, geben ein Promise zurück. Wenn die ESLint-Regel no-floating-promises aktiviert ist, sollten Sie diese entweder global oder für die betroffene Zeile deaktivieren.

Falls Ihre Anwendung diese Regel benötigt, sollten Sie entweder das Promise mit void kennzeichnen – oder eine async-Funktion verwenden, das Promise mit await aufrufen und dann den Funktionsaufruf mit void markieren. Dies gilt nicht, wenn die Methode innerhalb eines onClick-Handlers aufgerufen wird.

Die betroffenen Methoden sind:

router.push
router.replace
router.prefetch

Mögliche Lösungen

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

// Hier würden Sie den Benutzer abfragen und zurückgeben
const useUser = () => ({ user: null, loading: false })

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

  useEffect(() => {
    // Deaktivieren der Linting-Regel in der nächsten Zeile - Dies ist die sauberste Lösung
    // eslint-disable-next-line no-floating-promises
    router.push('/login')

    // Das von router.push zurückgegebene Promise mit void markieren
    if (!(user || loading)) {
      void router.push('/login')
    }
    // Oder eine async-Funktion verwenden, das Promise mit await aufrufen und dann den Funktionsaufruf mit void markieren
    async function handleRouteChange() {
      if (!(user || loading)) {
        await router.push('/login')
      }
    }
    void handleRouteChange()
  }, [user, loading])

  return <p>Weiterleitung...</p>
}

withRouter

Falls useRouter nicht die beste Option für Sie ist, kann withRouter dasselbe router-Objekt zu jeder Komponente hinzufügen.

Verwendung

import { withRouter } from 'next/router'

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

export default withRouter(Page)

TypeScript

Um Klassenkomponenten mit withRouter zu verwenden, muss die Komponente eine router-Prop akzeptieren:

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)