Verlinkung und Navigation

Es gibt vier Möglichkeiten, zwischen Routen in Next.js zu navigieren:

• Verwendung der <Link>-Komponente
• Verwendung des useRouter-Hooks (Client Components)
• Verwendung der redirect-Funktion (Server Components)
• Verwendung der nativen History API

Diese Seite erklärt, wie Sie diese Optionen verwenden können, und geht tiefer darauf ein, wie Navigation funktioniert.

<Link>-Komponente

<Link> ist eine eingebaute Komponente, die das HTML-<a>-Tag erweitert, um Prefetching und clientseitige Navigation zwischen Routen zu ermöglichen. Es ist die primäre und empfohlene Methode, um zwischen Routen in Next.js zu navigieren.

Sie können sie verwenden, indem Sie sie aus next/link importieren und der Komponente eine href-Prop übergeben:

import Link from 'next/link'

export default function Page() {
  return <Link href="/dashboard">Dashboard</Link>
}

import Link from 'next/link'

export default function Page() {
  return <Link href="/dashboard">Dashboard</Link>
}

Es gibt weitere optionale Props, die Sie an <Link> übergeben können. Weitere Informationen finden Sie in der API-Referenz.

Beispiele

Verlinkung zu dynamischen Segmenten

Beim Verlinken zu dynamischen Segmenten können Sie Template-Literale und Interpolation verwenden, um eine Liste von Links zu generieren. Zum Beispiel, um eine Liste von Blog-Posts zu generieren:

import Link from 'next/link'

export default function PostList({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>
          <Link href={`/blog/${post.slug}`}>{post.title}</Link>
        </li>
      ))}
    </ul>
  )
}

Überprüfung aktiver Links

Sie können usePathname() verwenden, um festzustellen, ob ein Link aktiv ist. Um beispielsweise eine Klasse zum aktiven Link hinzuzufügen, können Sie überprüfen, ob der aktuelle pathname mit dem href des Links übereinstimmt:

'use client'

import { usePathname } from 'next/navigation'
import Link from 'next/link'

export function Links() {
  const pathname = usePathname()

  return (
    <nav>
      <ul>
        <li>
          <Link className={`link ${pathname === '/' ? 'active' : ''}`} href="/">
            Home
          </Link>
        </li>
        <li>
          <Link
            className={`link ${pathname === '/about' ? 'active' : ''}`}
            href="/about"
          >
            About
          </Link>
        </li>
      </ul>
    </nav>
  )
}

'use client'

import { usePathname } from 'next/navigation'
import Link from 'next/link'

export function Links() {
  const pathname = usePathname()

  return (
    <nav>
      <ul>
        <li>
          <Link className={`link ${pathname === '/' ? 'active' : ''}`} href="/">
            Home
          </Link>
        </li>
        <li>
          <Link
            className={`link ${pathname === '/about' ? 'active' : ''}`}
            href="/about"
          >
            About
          </Link>
        </li>
      </ul>
    </nav>
  )
}

Scrollen zu einer id

Das Standardverhalten des Next.js App Routers ist es, zum Anfang einer neuen Route zu scrollen oder die Scroll-Position für Vor- und Zurück-Navigation beizubehalten.

Wenn Sie zu einer bestimmten id navigieren möchten, können Sie Ihre URL mit einem #-Hash-Link versehen oder einfach einen Hash-Link an die href-Prop übergeben. Dies ist möglich, da <Link> zu einem <a>-Element gerendert wird.

<Link href="/dashboard#settings">Settings</Link>

// Ausgabe
<a href="/dashboard#settings">Settings</a>

Gut zu wissen:

• Next.js scrollt zur Seite, wenn sie bei der Navigation nicht im Viewport sichtbar ist.

Deaktivierung der Scroll-Wiederherstellung

Das Standardverhalten des Next.js App Routers ist es, zum Anfang einer neuen Route zu scrollen oder die Scroll-Position für Vor- und Zurück-Navigation beizubehalten. Wenn Sie dieses Verhalten deaktivieren möchten, können Sie scroll={false} an die <Link>-Komponente oder scroll: false an router.push() oder router.replace() übergeben.

// next/link
<Link href="/dashboard" scroll={false}>
  Dashboard
</Link>

// useRouter
import { useRouter } from 'next/navigation'

const router = useRouter()

router.push('/dashboard', { scroll: false })

useRouter()-Hook

Der useRouter-Hook ermöglicht es Ihnen, Routen programmatisch aus Client Components zu ändern.

'use client'

import { useRouter } from 'next/navigation'

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

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

Eine vollständige Liste der useRouter-Methoden finden Sie in der API-Referenz.

Empfehlung: Verwenden Sie die <Link>-Komponente für die Navigation zwischen Routen, es sei denn, Sie haben einen spezifischen Grund, useRouter zu verwenden.

redirect-Funktion

Für Server Components verwenden Sie stattdessen die redirect-Funktion.

import { redirect } from 'next/navigation'

async function fetchTeam(id: string) {
  const res = await fetch('https://...')
  if (!res.ok) return undefined
  return res.json()
}

export default async function Profile({ params }: { params: { id: string } }) {
  const team = await fetchTeam(params.id)
  if (!team) {
    redirect('/login')
  }

  // ...
}

import { redirect } from 'next/navigation'

async function fetchTeam(id) {
  const res = await fetch('https://...')
  if (!res.ok) return undefined
  return res.json()
}

export default async function Profile({ params }) {
  const team = await fetchTeam(params.id)
  if (!team) {
    redirect('/login')
  }

  // ...
}

Gut zu wissen:

• redirect gibt standardmäßig einen 307 (Temporary Redirect)-Statuscode zurück. Bei Verwendung in einer Server Action gibt es einen 303 (See Other)-Code zurück, der häufig für die Weiterleitung zu einer Erfolgsseite nach einer POST-Anfrage verwendet wird.
• redirect wirft intern einen Fehler aus und sollte daher außerhalb von try/catch-Blöcken aufgerufen werden.
• redirect kann in Client Components während des Rendering-Prozesses aufgerufen werden, aber nicht in Event-Handlern. Verwenden Sie stattdessen den useRouter-Hook.
• redirect akzeptiert auch absolute URLs und kann für Weiterleitungen zu externen Links verwendet werden.
• Wenn Sie vor dem Rendering-Prozess weiterleiten möchten, verwenden Sie next.config.js oder Middleware.

Weitere Informationen finden Sie in der redirect-API-Referenz.

Verwendung der nativen History API

Next.js ermöglicht die Verwendung der nativen Methoden window.history.pushState und window.history.replaceState, um den Browserverlauf zu aktualisieren, ohne die Seite neu zu laden.

pushState- und replaceState-Aufrufe integrieren sich in den Next.js Router und ermöglichen die Synchronisation mit usePathname und useSearchParams.

window.history.pushState

Verwenden Sie diese Methode, um einen neuen Eintrag zum Browserverlauf hinzuzufügen. Der Benutzer kann zum vorherigen Zustand zurücknavigieren. Zum Beispiel, um eine Produktliste zu sortieren:

'use client'

import { useSearchParams } from 'next/navigation'

export default function SortProducts() {
  const searchParams = useSearchParams()

  function updateSorting(sortOrder: string) {
    const params = new URLSearchParams(searchParams.toString())
    params.set('sort', sortOrder)
    window.history.pushState(null, '', `?${params.toString()}`)
  }

  return (
    <>
      <button onClick={() => updateSorting('asc')}>Aufsteigend sortieren</button>
      <button onClick={() => updateSorting('desc')}>Absteigend sortieren</button>
    </>
  )
}

'use client'

import { useSearchParams } from 'next/navigation'

export default function SortProducts() {
  const searchParams = useSearchParams()

  function updateSorting(sortOrder) {
    const params = new URLSearchParams(searchParams.toString())
    params.set('sort', sortOrder)
    window.history.pushState(null, '', `?${params.toString()}`)
  }

  return (
    <>
      <button onClick={() => updateSorting('asc')}>Aufsteigend sortieren</button>
      <button onClick={() => updateSorting('desc')}>Absteigend sortieren</button>
    </>
  )
}

window.history.replaceState

Verwenden Sie diese Methode, um den aktuellen Eintrag im Browserverlauf zu ersetzen. Der Benutzer kann nicht zum vorherigen Zustand zurücknavigieren. Zum Beispiel, um die Locale der Anwendung zu wechseln:

'use client'

import { usePathname } from 'next/navigation'

export function LocaleSwitcher() {
  const pathname = usePathname()

  function switchLocale(locale: string) {
    // z.B. '/en/about' oder '/fr/contact'
    const newPath = `/${locale}${pathname}`
    window.history.replaceState(null, '', newPath)
  }

  return (
    <>
      <button onClick={() => switchLocale('en')}>Englisch</button>
      <button onClick={() => switchLocale('fr')}>Französisch</button>
    </>
  )
}

'use client'

import { usePathname } from 'next/navigation'

export function LocaleSwitcher() {
  const pathname = usePathname()

  function switchLocale(locale) {
    // z.B. '/en/about' oder '/fr/contact'
    const newPath = `/${locale}${pathname}`
    window.history.replaceState(null, '', newPath)
  }

  return (
    <>
      <button onClick={() => switchLocale('en')}>Englisch</button>
      <button onClick={() => switchLocale('fr')}>Französisch</button>
    </>
  )
}

Wie Routing und Navigation funktionieren

Der App Router verwendet einen hybriden Ansatz für Routing und Navigation. Auf dem Server wird Ihr Anwendungscode automatisch nach Code-Splitting nach Routensegmenten aufgeteilt. Und auf dem Client prefetcht und cached Next.js die Routensegmente. Das bedeutet, dass bei der Navigation zu einer neuen Route die Seite nicht neu geladen wird und nur die sich ändernden Routensegmente neu gerendert werden - was die Navigationserfahrung und Leistung verbessert.

1. Code-Splitting

Code-Splitting ermöglicht es, Ihren Anwendungscode in kleinere Bundles aufzuteilen, die vom Browser heruntergeladen und ausgeführt werden. Dies reduziert die übertragene Datenmenge und die Ausführungszeit für jede Anfrage, was zu einer verbesserten Leistung führt.

Server Components ermöglichen es, Ihren Anwendungscode automatisch nach Routensegmenten aufzuteilen. Das bedeutet, dass nur der Code für die aktuelle Route bei der Navigation geladen wird.

2. Prefetching

Prefetching ist eine Methode, um eine Route im Hintergrund vorzuladen, bevor der Benutzer sie besucht.

Es gibt zwei Möglichkeiten, wie Routen in Next.js geprefetched werden:

• <Link>-Komponente: Routen werden automatisch geprefetched, sobald sie im Viewport des Benutzers sichtbar werden. Prefetching erfolgt beim ersten Laden der Seite oder beim Scrollen.
• router.prefetch(): Der useRouter-Hook kann verwendet werden, um Routen programmatisch zu prefetchen.

Das Standard-Prefetching-Verhalten von <Link> (d.h. wenn die prefetch-Prop nicht angegeben oder auf null gesetzt ist) unterscheidet sich je nach Verwendung von loading.js. Nur das gemeinsame Layout bis zur ersten loading.js-Datei wird geprefetched und für 30s gecached. Dies reduziert die Kosten für das Abrufen einer gesamten dynamischen Route und ermöglicht es, einen sofortigen Ladezustand für bessere visuelle Rückmeldung an den Benutzer anzuzeigen.

Sie können Prefetching deaktivieren, indem Sie die prefetch-Prop auf false setzen. Alternativ können Sie die vollständigen Seitendaten über die Ladegrenzen hinaus prefetchen, indem Sie die prefetch-Prop auf true setzen.

Weitere Informationen finden Sie in der <Link>-API-Referenz.

Gut zu wissen:

• Prefetching ist nur in der Produktion aktiviert, nicht während der Entwicklung.

3. Caching

Next.js hat einen clientseitigen In-Memory-Cache namens Router Cache. Wenn Benutzer durch die App navigieren, werden die React Server Component Payloads von geprefetchten Routensegmenten und besuchten Routen im Cache gespeichert.

Das bedeutet, dass bei der Navigation der Cache so weit wie möglich wiederverwendet wird, anstatt eine neue Anfrage an den Server zu stellen - was die Leistung durch Reduzierung der Anfragen und übertragenen Daten verbessert.

Erfahren Sie mehr darüber, wie der Router Cache funktioniert und wie Sie ihn konfigurieren können.

4. Partielles Rendering

Partielles Rendering bedeutet, dass nur die Routensegmente, die sich bei der Navigation ändern, auf dem Client neu gerendert werden, während gemeinsame Segmente erhalten bleiben.

Beispielsweise werden bei der Navigation zwischen zwei Geschwisterrouten /dashboard/settings und /dashboard/analytics die settings- und analytics-Seiten gerendert, während das gemeinsame dashboard-Layout erhalten bleibt.

Ohne partielles Rendering würde jede Navigation ein vollständiges Neu-Rendering der Seite auf dem Client verursachen. Das Rendern nur des sich ändernden Segments reduziert die übertragene Datenmenge und die Ausführungszeit, was zu einer verbesserten Leistung führt.

5. Soft Navigation

Browser führen eine "Hard Navigation" zwischen Seiten durch. Der Next.js App Router ermöglicht "Soft Navigation" zwischen Seiten, wobei nur die sich ändernden Routensegmente neu gerendert werden (partielles Rendering). Dadurch bleibt der clientseitige React-Status während der Navigation erhalten.

6. Vor- und Zurück-Navigation

Standardmäßig behält Next.js die Scroll-Position für Vor- und Zurück-Navigation bei und verwendet Routensegmente aus dem Router Cache wieder.

7. Routing zwischen pages/ und app/

Bei der schrittweisen Migration von pages/ zu app/ behandelt der Next.js Router automatisch Hard Navigation zwischen den beiden. Um Übergänge von pages/ zu app/ zu erkennen, gibt es einen Client-Router-Filter, der probabilistische Überprüfungen von App-Routen nutzt, was gelegentlich zu falsch positiven Ergebnissen führen kann. Standardmäßig sollten solche Vorkommnisse sehr selten sein, da wir die Wahrscheinlichkeit für falsch positive Ergebnisse auf 0,01 % konfigurieren. Diese Wahrscheinlichkeit kann über die Option experimental.clientRouterFilterAllowedRate in next.config.js angepasst werden. Es ist wichtig zu beachten, dass eine niedrigere falsch positive Rate die Größe des generierten Filters im Client-Bundle erhöht.

Alternativ können Sie diese Behandlung komplett deaktivieren und das Routing zwischen pages/ und app/ manuell verwalten, indem Sie experimental.clientRouterFilter in next.config.js auf false setzen. Wenn diese Funktion deaktiviert ist, werden dynamische Routen in pages, die mit app-Routen überlappen, standardmäßig nicht korrekt navigiert.