<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.

Betrachten Sie als Beispiel ein pages-Verzeichnis mit folgenden Dateien:

• pages/index.js
• pages/about.js
• pages/blog/[slug].js

Wir können wie folgt einen Link zu jeder dieser Seiten erstellen:

import Link from 'next/link'

function Home() {
  return (
    <ul>
      <li>
        <Link href="/">Startseite</Link>
      </li>
      <li>
        <Link href="/about">Über uns</Link>
      </li>
      <li>
        <Link href="/blog/hello-world">Blogbeitrag</Link>
      </li>
    </ul>
  )
}

export default Home

Props

Hier eine Übersicht der verfügbaren Props für die Link-Komponente:

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.

<Link href="/dashboard">Dashboard</Link>

href kann auch ein Objekt akzeptieren, zum Beispiel:

// Navigiere zu /about?name=test
<Link
  href={{
    pathname: '/about',
    query: { name: 'test' },
  }}
>
  Über uns
</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 Page() {
  return (
    <Link href="/dashboard" replace>
      Dashboard
    </Link>
  )
}

import Link from 'next/link'

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

scroll

Standardwert: true. Das Standardverhalten von <Link> ist, nach einer Navigation zum Anfang der neuen Route zu scrollen oder die Scrollposition bei Vor- und Zurück-Navigation beizubehalten. Wenn false, scrollt next/link nach einer Navigation nicht zum Seitenanfang.

import Link from 'next/link'

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

import Link from 'next/link'

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

Gut zu wissen:

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

prefetch

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 Daten im Hintergrund, um die Leistung der clientseitigen Navigation zu verbessern. Prefetching ist nur in der Produktion aktiviert.

• true (Standard): Die vollständige Route und ihre Daten werden prefetched.
• false: Prefetching erfolgt nicht beim Eintritt in den Viewport, aber beim Hover. Wenn Sie Prefetching komplett deaktivieren möchten, erwägen Sie die Verwendung eines <a>-Tags oder die schrittweise Migration zum App-Router, der auch das Deaktivieren von Prefetching beim Hover ermöglicht.

import Link from 'next/link'

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

import Link from 'next/link'

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

Weitere Props

legacyBehavior

Ein <a>-Element ist nicht mehr als Kind von <Link> erforderlich. Fügen Sie die legacyBehavior-Prop hinzu, um das Legacy-Verhalten zu verwenden, oder entfernen Sie das <a>-Element für ein Upgrade. Ein Codemod ist verfügbar, um Ihren Code automatisch zu aktualisieren.

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-Property an sein Kind weitergibt. Standardwert: false

scroll

Scrollt nach einer Navigation zum Seitenanfang. Standardwert: true

shallow

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

locale

Die aktive Locale wird automatisch vorangestellt. locale ermöglicht das Angeben einer anderen Locale. Wenn false, muss href die Locale enthalten, da das Standardverhalten deaktiviert ist.

Beispiele

Verlinkung zu dynamischen Routen

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

Sie können beispielsweise 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>
  )
}

export default Posts

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 Seite beeinträchtigen und sich auf die SEO auswirken kann. Wenn Sie ESLint verwenden, gibt es eine integrierte 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 verwenden, auch wenn Sie direkt ein <a>-Tag verwenden.
• Die Komponente sollte die onClick-Property unterstützen, um die Navigation korrekt auszulösen

Wenn das Kind eine Funktionskomponente ist

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

import Link from 'next/link'

// `onClick`, `href` und `ref` müssen an das DOM-Element übergeben werden
// für die korrekte Handhabung
const MyButton = React.forwardRef(({ onClick, href }, ref) => {
  return (
    <a href={href} onClick={onClick} ref={ref}>
      Klick mich
    </a>
  )
})

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

export default Home

Mit URL-Objekt

Link kann auch ein URL-Objekt erhalten und formatiert es automatisch, um die URL-Zeichenkette zu erstellen. Hier ist ein Beispiel:

import Link from 'next/link'

function Home() {
  return (
    <ul>
      <li>
        <Link
          href={{
            pathname: '/about',
            query: { name: 'test' },
          }}
        >
          Über uns
        </Link>
      </li>
      <li>
        <Link
          href={{
            pathname: '/blog/[slug]',
            query: { slug: 'my-post' },
          }}
        >
          Blogbeitrag
        </Link>
      </li>
    </ul>
  )
}

export default Home

Das obige Beispiel enthält Links 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 hinzufügen

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

<Link href="/about" replace>
  Über uns
</Link>

Scrollen zum Seitenanfang deaktivieren

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

<Link href="/#hashid" scroll={false}>
  Deaktiviert das Scrollen zum Anfang
</Link>

Middleware

Es ist üblich, Middleware für Authentifizierung oder andere Zwecke zu verwenden, die das Umleiten 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 Abfragen an die Middleware zu vermeiden, um die korrekte Route zum Prefetchen zu ermitteln.

Wenn Sie beispielsweise eine /dashboard-Route bereitstellen möchten, die authentifizierte und Besucher-Ansichten hat, können Sie in Ihrer Middleware etwa Folgendes hinzufügen, um den Benutzer zur richtigen Seite umzuleiten:

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

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

import Link from 'next/link'
import useIsAuthed from './hooks/useIsAuthed'

export default function Page() {
  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. Wenn Sie beispielsweise eine Dynamische Route wie /dashboard/authed/[user] haben, die Sie über Middleware anders präsentieren möchten, würden Sie schreiben: <Link href={{ pathname: '/dashboard/authed/[user]', query: { user: username } }} as="/dashboard/[user]">Profil</Link>.

Versionsverlauf