<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="/">Home</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 zugrundeliegende <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 in den Browserverlauf einzufü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 Seitenanfang 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>
  )
}

prefetch

Standardwert: true. Wenn true, lädt next/link die Seite (angegeben durch href) im Hintergrund vor. Dies ist nützlich, um die Leistung von clientseitigen Navigationen zu verbessern. Jeder <Link /> im Viewport (initial oder durch Scrollen) wird vorab geladen.

Das Prefetching kann durch prefetch={false} deaktiviert werden. Prefetching ist nur in der Produktionsumgebung aktiviert.

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

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>
  )
}

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 Website 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 einbinden:

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

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

Deaktivieren des Scrollens zum Seitenanfang

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 Seitenanfang/Hash zu verhindern, kann scroll={false} zu Link hinzugefügt werden:

<Link href="/#hashid" scroll={false}>
  Deaktiviert das Scrollen zum Seitenanfang
</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 Anfragen an die Middleware zu vermeiden, um die korrekte Route zum Prefetchen zu ermitteln.

Beispiel: Wenn Sie eine /dashboard-Route bereitstellen möchten, die authentifizierte und Besucher-Ansichten hat, können Sie in Ihrer Middleware etwas Ähnliches wie folgt 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 den 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' : '/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/[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