Link

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

Grundlegende Verwendung:

import Link from 'next/link'

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

Referenz

Die folgenden Props können an die <Link>-Komponente übergeben werden:

Gut zu wissen: Attribute des <a>-Tags wie className oder target="_blank" können als Props an <Link> übergeben werden und werden an das zugrunde liegende <a>-Element weitergegeben.

href (erforderlich)

Der Pfad oder die URL, zu der navigiert werden soll.

import Link from 'next/link'

// Navigiere zu /about?name=test
export default function Home() {
  return (
    <Link
      href={{
        pathname: '/about',
        query: { name: 'test' },
      }}
    >
      About
    </Link>
  )
}

replace

Standardwert: false. Wenn true, ersetzt next/link den aktuellen Verlaufseintrag, anstatt eine neue URL zum Browserverlauf hinzuzufügen.

import Link from 'next/link'

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

scroll

Standardwert: true. Das standardmäßige Scrollverhalten von <Link> in Next.js ist die Beibehaltung der Scrollposition, ähnlich wie Browser mit der Navigation vor und zurück umgehen. Wenn Sie zu einer neuen Seite navigieren, bleibt die Scrollposition gleich, solange die Seite im Viewport sichtbar ist. Wenn die Seite jedoch nicht im Viewport sichtbar ist, scrollt Next.js zum obersten Element der Seite.

Wenn scroll = {false}, versucht Next.js nicht, zum ersten Seitenelement zu scrollen.

Gut zu wissen: Next.js prüft scroll: false, bevor es das Scrollverhalten verwaltet. Wenn das Scrollen aktiviert ist, identifiziert es den relevanten DOM-Knoten für die Navigation und überprüft jedes Top-Level-Element. Alle nicht scrollbaren Elemente und solche ohne gerendertes HTML werden übersprungen, einschließlich Elementen mit fester oder sticky Positionierung und nicht sichtbaren Elementen, die mit getBoundingClientRect berechnet werden. Next.js durchläuft dann die Geschwisterelemente, bis es ein scrollbares Element findet, das im Viewport sichtbar ist.

import Link from 'next/link'

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

prefetch

Das Prefetching erfolgt, wenn eine <Link />-Komponente in den Viewport des Benutzers gelangt (initial oder durch Scrollen). Next.js lädt die verlinkte Route (angegeben durch href) und die Daten im Hintergrund vor, um die Leistung der clientseitigen Navigation zu verbessern. Prefetching ist nur in der Produktion aktiviert.

Die folgenden Werte können an die prefetch-Prop übergeben werden:

• true (Standard): Die vollständige Route und ihre Daten werden vorab geladen.
• false: Prefetching erfolgt nicht beim Eintritt in den Viewport, aber beim Hover. Wenn Sie das Prefetching beim Hover vollständig deaktivieren möchten, sollten Sie ein <a>-Tag verwenden oder inkrementell migrieren zum App-Router, der auch das Deaktivieren des Prefetchings beim Hover ermöglicht.

import Link from 'next/link'

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

legacyBehavior

Warnung: Die legacyBehavior-Prop wird in Next.js v16 entfernt. Um das neue <Link>-Verhalten zu übernehmen, entfernen Sie alle <a>-Tags, die als Kinder von <Link> verwendet werden. Ein Codemod ist verfügbar, um Ihnen bei der automatischen Aktualisierung Ihres Codebase zu helfen.

Seit Version 13 ist ein <a>-Element nicht mehr als Kind der <Link>-Komponente erforderlich. Wenn Sie das alte Verhalten aus Kompatibilitätsgründen dennoch benötigen, können Sie die legacyBehavior-Prop hinzufügen.

Gut zu wissen: Wenn legacyBehavior nicht auf true gesetzt ist, können alle anchor-Tag-Eigenschaften wie className, onClick usw. auch an next/link übergeben werden.

passHref

Erzwingt, dass Link die href-Eigenschaft an sein Kind weitergibt. Standardwert ist false. Siehe das Beispiel Übergeben einer funktionalen Komponente für weitere Informationen.

shallow

Aktualisiert den Pfad der aktuellen Seite, ohne getStaticProps, getServerSideProps oder getInitialProps erneut auszuführen. Standardwert ist false.

import Link from 'next/link'

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

locale

Die aktive Locale wird automatisch vorangestellt. Mit locale kann eine andere Locale angegeben werden. Wenn false, muss href die Locale enthalten, da das Standardverhalten deaktiviert ist.

import Link from 'next/link'

export default function Home() {
  return (
    <>
      {/* Standardverhalten: Locale wird vorangestellt */}
      <Link href="/dashboard">Dashboard (mit Locale)</Link>

      {/* Deaktiviert das Voranstellen der Locale */}
      <Link href="/dashboard" locale={false}>
        Dashboard (ohne Locale)
      </Link>

      {/* Gibt eine andere Locale an */}
      <Link href="/dashboard" locale="fr">
        Dashboard (Französisch)
      </Link>
    </>
  )
}

onNavigate

Ein Event-Handler, der während der clientseitigen Navigation aufgerufen wird. Der Handler empfängt ein Event-Objekt, das eine preventDefault()-Methode enthält, mit der Sie die Navigation bei Bedarf abbrechen können.

import Link from 'next/link'

export default function Page() {
  return (
    <Link
      href="/dashboard"
      onNavigate={(e) => {
        // Wird nur während der SPA-Navigation ausgeführt
        console.log('Navigiere...')

        // Optional Navigation abbrechen
        // e.preventDefault()
      }}
    >
      Dashboard
    </Link>
  )
}

Gut zu wissen: Obwohl onClick und onNavigate ähnlich erscheinen mögen, dienen sie unterschiedlichen Zwecken. onClick wird für alle Klick-Events ausgeführt, während onNavigate nur während der clientseitigen Navigation läuft. Einige wichtige Unterschiede:

• Bei Verwendung von Modifikatortasten (Strg/Cmd + Klick) wird onClick ausgeführt, aber nicht onNavigate, da Next.js die Standardnavigation für neue Tabs verhindert.
• Externe URLs lösen onNavigate nicht aus, da es nur für clientseitige und same-origin-Navigationen gilt.
• Links mit dem download-Attribut funktionieren mit onClick, aber nicht mit onNavigate, da der Browser die verlinkte URL als Download behandelt.

Beispiele

Die folgenden Beispiele zeigen, wie die <Link>-Komponente in verschiedenen Szenarien verwendet wird.

Verlinkung zu dynamischen Routensegmenten

Für dynamische Routensegmente kann es praktisch sein, Template-Literale zu verwenden, um den Pfad des Links zu erstellen.

Beispielsweise können Sie eine Liste von Links zur dynamischen Route pages/blog/[slug].js generieren:

import Link from 'next/link'

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

Wenn das Kind eine benutzerdefinierte Komponente ist, die ein <a>-Tag umschließt

Wenn das Kind von Link eine benutzerdefinierte Komponente ist, die ein <a>-Tag umschließt, müssen Sie passHref zu Link hinzufügen. Dies ist notwendig, wenn Sie Bibliotheken wie styled-components verwenden. Ohne dies hat das <a>-Tag kein href-Attribut, was die Barrierefreiheit Ihrer Website beeinträchtigt und sich möglicherweise auf die SEO auswirkt. Wenn Sie ESLint verwenden, gibt es eine eingebaute Regel next/link-passhref, um die korrekte Verwendung von passHref sicherzustellen.

import Link from 'next/link'
import styled from 'styled-components'

// Dies erstellt eine benutzerdefinierte Komponente, die ein <a>-Tag umschließt
const RedLink = styled.a`
  color: red;
`

function NavLink({ href, name }) {
  return (
    <Link href={href} passHref legacyBehavior>
      <RedLink>{name}</RedLink>
    </Link>
  )
}

export default NavLink

• Wenn Sie die JSX-Pragma-Funktion (@jsx jsx) von emotion verwenden, müssen Sie passHref auch dann verwenden, wenn Sie direkt ein <a>-Tag verwenden.
• Die Komponente sollte die onClick-Property unterstützen, um die Navigation korrekt auszulösen.

Verschachtelung einer funktionalen Komponente

Wenn das Kind von Link eine funktionale Komponente ist, müssen Sie zusätzlich zu passHref und legacyBehavior die Komponente in React.forwardRef wrappen:

import Link from 'next/link'
import React from 'react'

// Definieren Sie den Props-Typ für MyButton
interface MyButtonProps {
  onClick?: React.MouseEventHandler<HTMLAnchorElement>
  href?: string
}

// Verwenden Sie React.ForwardRefRenderFunction, um den weitergeleiteten Ref korrekt zu typisieren
const MyButton: React.ForwardRefRenderFunction<
  HTMLAnchorElement,
  MyButtonProps
> = ({ onClick, href }, ref) => {
  return (
    <a href={href} onClick={onClick} ref={ref}>
      Click Me
    </a>
  )
}

// Verwenden Sie React.forwardRef, um die Komponente zu wrappen
const ForwardedMyButton = React.forwardRef(MyButton)

export default function Home() {
  return (
    <Link href="/about" passHref legacyBehavior>
      <ForwardedMyButton />
    </Link>
  )
}

Übergeben eines URL-Objekts

Link kann auch ein URL-Objekt empfangen und es automatisch formatieren, um die URL-Zeichenkette zu erstellen:

import Link from 'next/link'

function Home() {
  return (
    <ul>
      <li>
        <Link
          href={{
            pathname: '/about',
            query: { name: 'test' },
          }}
        >
          About us
        </Link>
      </li>
      <li>
        <Link
          href={{
            pathname: '/blog/[slug]',
            query: { slug: 'my-post' },
          }}
        >
          Blog Post
        </Link>
      </li>
    </ul>
  )
}

export default Home

Das obige Beispiel enthält einen Link zu:

• Einer vordefinierten Route: /about?name=test
• Einer dynamischen Route: /blog/my-post

Sie können jede Property verwenden, wie in der Node.js URL-Modul-Dokumentation definiert.

URL ersetzen statt pushen

Das Standardverhalten der Link-Komponente besteht darin, eine neue URL in den history-Stack zu pushen. Sie können die replace-Prop verwenden, um das Hinzufügen eines neuen Eintrags zu verhindern, wie im folgenden Beispiel:

import Link from 'next/link'

export default function Home() {
  return (
    <Link href="/about" replace>
      About us
    </Link>
  )
}

import Link from 'next/link'

export default function Home() {
  return (
    <Link href="/about" replace>
      About us
    </Link>
  )
}

Scrollen zum Seitenanfang deaktivieren

Das Standardverhalten von Link ist das Scrollen zum Seitenanfang. Wenn ein Hash definiert ist, wird zur spezifischen id gescrollt, wie bei einem normalen <a>-Tag. Um das Scrollen zum Seitenanfang / Hash zu verhindern, kann scroll={false} zu Link hinzugefügt werden:

import Link from 'next/link'

export default function Home() {
  return (
    <Link href="/#hashid" scroll={false}>
      Deaktiviert das Scrollen zum Seitenanfang
    </Link>
  )
}

Prefetching von Links in Middleware

Es ist üblich, Middleware für Authentifizierung oder andere Zwecke zu verwenden, die eine Umleitung des Benutzers auf eine andere Seite beinhalten. Damit die <Link />-Komponente Links mit Rewrites über Middleware korrekt prefetchen kann, müssen Sie Next.js sowohl die anzuzeigende URL als auch die zu prefetchende URL mitteilen. Dies ist notwendig, um unnötige Anfragen an die Middleware zu vermeiden, um die korrekte Route für das Prefetching zu ermitteln.

Beispiel: Wenn Sie eine /dashboard-Route bereitstellen möchten, die authentifizierte und Besucher-Ansichten hat, können Sie folgendes in Ihrer Middleware hinzufügen, um den Benutzer auf die richtige Seite umzuleiten:

import { NextResponse } from 'next/server'

export function middleware(request: Request) {
  const nextUrl = request.nextUrl
  if (nextUrl.pathname === '/dashboard') {
    if (request.cookies.authToken) {
      return NextResponse.rewrite(new URL('/auth/dashboard', request.url))
    } else {
      return NextResponse.rewrite(new URL('/public/dashboard', request.url))
    }
  }
}

In diesem Fall würden Sie folgenden Code in Ihrer <Link />-Komponente verwenden:

'use client'

import Link from 'next/link'
import useIsAuthed from './hooks/useIsAuthed' // Ihr Authentifizierungs-Hook

export default function Home() {
  const isAuthed = useIsAuthed()
  const path = isAuthed ? '/auth/dashboard' : '/public/dashboard'
  return (
    <Link as="/dashboard" href={path}>
      Dashboard
    </Link>
  )
}

Gut zu wissen: Wenn Sie Dynamische Routen verwenden, müssen Sie Ihre as- und href-Props anpassen. Beispiel: Wenn Sie eine dynamische Route wie /dashboard/authed/[user] haben, die Sie über Middleware anders darstellen möchten, würden Sie schreiben: <Link href={{ pathname: '/dashboard/authed/[user]', query: { user: username } }} as="/dashboard/[user]">Profil</Link>.

Blockieren der Navigation

Sie können die onNavigate-Prop verwenden, um die Navigation zu blockieren, wenn bestimmte Bedingungen erfüllt sind, z.B. wenn ein Formular ungespeicherte Änderungen enthält. Wenn Sie die Navigation über mehrere Komponenten in Ihrer App hinweg blockieren müssen (z.B. um die Navigation von jedem Link zu verhindern, während ein Formular bearbeitet wird), bietet React Context eine saubere Möglichkeit, diesen Blockierstatus zu teilen. Erstellen Sie zunächst einen Context, um den Blockierstatus der Navigation zu verfolgen:

'use client'

import { createContext, useState, useContext } from 'react'

interface NavigationBlockerContextType {
  isBlocked: boolean
  setIsBlocked: (isBlocked: boolean) => void
}

export const NavigationBlockerContext =
  createContext<NavigationBlockerContextType>({
    isBlocked: false,
    setIsBlocked: () => {},
  })

export function NavigationBlockerProvider({
  children,
}: {
  children: React.ReactNode
}) {
  const [isBlocked, setIsBlocked] = useState(false)

  return (
    <NavigationBlockerContext.Provider value={{ isBlocked, setIsBlocked }}>
      {children}
    </NavigationBlockerContext.Provider>
  )
}

export function useNavigationBlocker() {
  return useContext(NavigationBlockerContext)
}

Erstellen Sie eine Formularkomponente, die den Context verwendet:

'use client'

import { useNavigationBlocker } from '../contexts/navigation-blocker'

export default function Form() {
  const { setIsBlocked } = useNavigationBlocker()

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault()
        setIsBlocked(false)
      }}
      onChange={() => setIsBlocked(true)}
    >
      <input type="text" name="name" />
      <button type="submit">Speichern</button>
    </form>
  )
}

Erstellen Sie eine benutzerdefinierte Link-Komponente, die die Navigation blockiert:

'use client'

import Link from 'next/link'
import { useNavigationBlocker } from '../contexts/navigation-blocker'

interface CustomLinkProps extends React.ComponentProps<typeof Link> {
  children: React.ReactNode
}

export function CustomLink({ children, ...props }: CustomLinkProps) {
  const { isBlocked } = useNavigationBlocker()

  return (
    <Link
      onNavigate={(e) => {
        if (
          isBlocked &&
          !window.confirm('Sie haben ungespeicherte Änderungen. Trotzdem verlassen?')
        ) {
          e.preventDefault()
        }
      }}
      {...props}
    >
      {children}
    </Link>
  )
}

Erstellen Sie eine Navigationskomponente:

'use client'

import { CustomLink as Link } from './custom-link'

export default function Nav() {
  return (
    <nav>
      <Link href="/">Startseite</Link>
      <Link href="/about">Über uns</Link>
    </nav>
  )
}

Schließlich umschließen Sie Ihre App mit dem NavigationBlockerProvider im Root-Layout und verwenden die Komponenten in Ihrer Seite:

import { NavigationBlockerProvider } from './contexts/navigation-blocker'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <NavigationBlockerProvider>{children}</NavigationBlockerProvider>
      </body>
    </html>
  )
}

Verwenden Sie dann die Nav- und Form-Komponenten in Ihrer Seite:

import Nav from './components/nav'
import Form from './components/form'

export default function Page() {
  return (
    <div>
      <Nav />
      <main>
        <h1>Willkommen im Dashboard</h1>
        <Form />
      </main>
    </div>
  )
}

Wenn ein Benutzer versucht, mit CustomLink wegzunavigieren, während das Formular ungespeicherte Änderungen enthält, wird er aufgefordert, dies zu bestätigen, bevor er die Seite verlässt.

Versionsverlauf