<Link>

<Link> ist eine React-Komponente, die das HTML-Element <a> erweitert, um Prefetching und clientseitige Navigation zwischen Routen zu ermöglichen. Es ist der primäre Weg, 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

Der <Link>-Komponente können folgende Props übergeben werden:

Hinweis: <a>-Tag-Attribute wie className oder target="_blank" können <Link> als Props hinzugefügt 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

Standardmäßig false. Wenn true, ersetzt next/link den aktuellen Verlaufszustand, anstatt eine neue URL in den Browsing-Verlauf hinzuzufügen.

import Link from 'next/link'
 
export default function Home() {
  return (
    <Link href="/dashboard" replace>
      Dashboard
    </Link>
  )
}

scroll

Standardmäßig true. Das standardmäßige Scroll-Verhalten von <Link> in Next.js ist die Beibehaltung der Scroll-Position, ähnlich wie Browser Back- und Forward-Navigation handhaben. Beim Navigieren zu einer neuen Seite bleibt die Scroll-Position gleich, solange die Seite im Viewport sichtbar ist. Wenn die Seite jedoch nicht im Viewport sichtbar ist, scrollt Next.js zum Anfang des ersten Seitenelements.

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

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 den Viewport des Benutzers betritt (initial oder durch Scrollen). Next.js lädt die verknüpfte Route (gekennzeichnet durch href) und die Daten im Hintergrund, um die Leistung der clientseitigen Navigation zu verbessern. Prefetching ist nur in der Produktionsumgebung aktiviert.

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

• true (Standard): Die vollständige Route und ihre Daten werden prefetcht.
• false: Prefetching erfolgt nicht beim Betreten des Viewports, sondern beim Hovern. Wenn Sie das Prefetching beim Hovern komplett deaktivieren möchten, verwenden Sie ein <a> Tag oder migrieren Sie schrittweise zum App Router, der das Deaktivieren des Hovern-Prefetchings ermöglicht.

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

legacyBehavior

Ein <a>-Element ist nicht mehr als Kind von <Link> erforderlich. Fügen Sie die legacyBehavior-Eigenschaft hinzu, um das Legacy-Verhalten zu verwenden, oder entfernen Sie das <a>, um zu aktualisieren. Ein Codemod steht zur automatischen Code-Aktualisierung zur Verfügung.

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

passHref

Zwingt Link, die href-Eigenschaft an sein Kind zu senden. Standard ist false. Weitere Informationen finden Sie im Beispiel zum Übergeben einer Funktionskomponente.

scroll

Nach der Navigation zum Seitenanfang scrollen. Standard ist true.

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

shallow

Aktualisiert den Pfad der aktuellen Seite ohne erneutes Ausführen von getStaticProps, getServerSideProps oder getInitialProps. Standard ist false.

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

locale

Die aktive Sprache wird automatisch vorangestellt. locale ermöglicht die Angabe einer anderen Sprache. Bei false muss href die Sprache enthalten, da das Standardverhalten deaktiviert ist.

import Link from 'next/link'
 
export default function Home() {
  return (
    <>
      {/* Standardverhalten: Sprache wird vorangestellt */}
      <Link href="/dashboard">Dashboard (mit Sprache)</Link>
 
      {/* Sprache-Voranstellung deaktivieren */}
      <Link href="/dashboard" locale={false}>
        Dashboard (ohne Sprache)
      </Link>
 
      {/* Andere Sprache angeben */}
      <Link href="/dashboard" locale="fr">
        Dashboard (Französisch)
      </Link>
    </>
  )
}

Beispiele

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

Mit dynamischen Routensegmenten verlinken

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

Zum Beispiel 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 wird dem <a>-Tag das href-Attribut fehlen, was die Zugänglichkeit Ihrer Website beeinträchtigt und die SEO beeinflussen 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

• Bei Verwendung von emotion's JSX-Pragma-Funktion (@jsx jsx) müssen Sie passHref verwenden, selbst wenn Sie ein <a>-Tag direkt verwenden.
• Die Komponente sollte die onClick-Eigenschaft unterstützen, um die Navigation korrekt auszulösen.

Verschachtelung einer Funktionskomponente

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

import Link from 'next/link'
import React from 'react'
 
// Definieren Sie den Eigenschaftstyp 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 einzuwickeln
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 formatiert es automatisch zur Erstellung des URL-Strings:

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 hat einen Link zu:

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

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

Die URL ersetzen statt einen neuen Eintrag hinzuzufügen

Das Standardverhalten der Link-Komponente besteht darin, eine neue URL in den history-Stack zu pushen. Sie können die replace-Eigenschaft 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>
  )
}

Scrollen zur Seitenspitze deaktivieren

Das Standardverhalten von Link ist es, zum Seitenanfang zu scrollen. Wenn eine Hash-Kennung definiert ist, scrollt es zur spezifischen ID, wie ein normales <a>-Tag. Um das Scrollen zum Seitenanfang / zur Hash-Kennung 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}>
      Scrollen zur Seitenspitze deaktivieren
    </Link>
  )
}

Links in Middleware vorprefetchen

Es ist üblich, Middleware für Authentifizierung oder andere Zwecke zu verwenden, bei denen der Benutzer auf eine andere Seite umgeleitet wird. Damit die <Link />-Komponente Links mit Rewrites über Middleware korrekt vorprefetchen kann, müssen Sie Next.js sowohl die anzuzeigende URL als auch die vorzupfetchende URL mitteilen. Dies ist erforderlich, um unnötige Anfragen an die Middleware zu vermeiden, um die korrekte Route zum Vorprefetchen zu ermitteln.

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

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

import { NextResponse } from 'next/server'
 
export function middleware(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 den folgenden Code in Ihrer <Link />-Komponente verwenden:

'use client'
 
import Link from 'next/link'
import useIsAuthed from './hooks/useIsAuthed' // Ihr Auth-Hook
 
export default function Home() {
  const isAuthed = useIsAuthed()
  const path = isAuthed ? '/auth/dashboard' : '/public/dashboard'
  return (
    <Link as="/dashboard" href href={path}>
      Dashboard
    </Link>
  )
}

'use client'
 
import Link from 'next/link'
import useIsAuthed from './hooks/useIsAuthed' // Ihr Auth-Hook
 
export default function Home() {
  const isAuthed = useIsAuthed()
  const path = isAuthed ? '/auth/dashboard' : '/public/dashboard'
  return (
    <Link as="/dashboard" href={path}>
      Dashboard
    </Link>
  )
}

Hinweis: 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 darstellen möchten, würden Sie Folgendes schreiben: <Link href={{ pathname: '/dashboard/authed/[user]', query: { user: username } }} as="/dashboard/[user]">Profil</Link>.

Versionshistorie