<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 Page() {
  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 Page() {
  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 Page() {
  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 Page() {
  return (
    <Link href="/dashboard" scroll={false}>
      Dashboard
    </Link>
  )
}

prefetch

Prefetching passiert, wenn eine <Link />-Komponente in den Viewport des Benutzers eintritt (initial oder durch Scrollen). Next.js prefetcht und lädt die verlinkte Route (gekennzeichnet durch href) und ihre Daten im Hintergrund, um die Performance von clientseitigen Navigationen zu verbessern. Wenn die geprefetchten Daten abgelaufen sind, wenn der Benutzer mit der Maus über einen <Link /> fährt, versucht Next.js, sie erneut zu prefetchen. Prefetching ist nur in der Produktionsumgebung aktiviert.

Der prefetch Prop können folgende Werte übergeben werden:

• null (Standard): Das Prefetching-Verhalten hängt davon ab, ob die Route statisch oder dynamisch ist. Bei statischen Routen wird die gesamte Route geprefetcht (einschließlich aller Daten). Bei dynamischen Routen wird der Teilpfad bis zur nächstgelegenen Segmentgrenze mit einer loading.js-Begrenzung geprefetcht.
• true: Die gesamte Route wird für statische und dynamische Routen geprefetcht.
• false: Prefetching wird weder beim Betreten des Viewports noch beim Hovern durchgeführt.

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

Beispiele

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

Mit dynamischen Segmenten verlinken

Beim Verlinken auf dynamische Segmente können Sie Template-Literale und Interpolation verwenden, um eine Liste von Links zu generieren. Zum Beispiel, um eine Liste von Blog-Beiträgen zu generieren:

import Link from 'next/link'
 
interface Post {
  id: number
  title: string
  slug: string
}
 
export default function PostList({ posts }: { posts: Post[] }) {
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>
          <Link href={`/blog/${post.slug}`}>{post.title}</Link>
        </li>
      ))}
    </ul>
  )
}

Aktive Links überprüfen

Sie können usePathname() verwenden, um zu bestimmen, ob ein Link aktiv ist. Zum Beispiel, um einem aktiven Link eine Klasse 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>
      <Link className={`link ${pathname === '/' ? 'active' : ''}`} href="/">
        Home
      </Link>
 
      <Link
        className={`link ${pathname === '/about' ? 'active' : ''}`}
        href="/about"
      >
        About
      </Link>
    </nav>
  )
}

Zu einer id scrollen

Wenn Sie beim Navigieren zu einer bestimmten id scrollen möchten, können Sie Ihre URL mit einem # Hash-Link anhängen oder einfach einen Hash-Link an die href-Eigenschaft übergeben. Dies ist möglich, da <Link> zu einem <a>-Element rendert.

<Link href="/dashboard#settings">Einstellungen</Link>
 
// Ausgabe
<a href="/dashboard#settings">Einstellungen</a>

Hinweis:

• Next.js scrollt zur Seite, wenn sie beim Navigieren nicht im Viewport sichtbar ist.

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 app/blog/[slug]/page.js generieren:

import Link from 'next/link'
 
export default function Page({ 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 Page() {
  return (
    <Link href="/about" passHref legacyBehavior>
      <ForwardedMyButton />
    </Link>
  )
}

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 Page() {
  return (
    <Link href="/about" replace>
      About us
    </Link>
  )
}

Scrollen zur Seitenspitze deaktivieren

Das Standardscroll-Verhalten von <Link> in Next.js behält die Scroll-Position bei, ähnlich wie Browser die Navigation vor und zurück handhaben. Wenn Sie zu einer neuen Seite navigieren, 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 Sie dieses Verhalten deaktivieren möchten, können Sie scroll={false} an die <Link> Komponente übergeben oder scroll: false an router.push() oder router.replace().

import Link from 'next/link'
 
export default function Page() {
  return (
    <Link href="/#hashid" scroll={false}>
      Scrollen zur Seitenspitze deaktivieren
    </Link>
  )
}

Verwendung von router.push() oder router.replace():

// useRouter
import { useRouter } from 'next/navigation'
 
const router = useRouter()
 
router.push('/dashboard', { scroll: false })

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 Page() {
  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 Page() {
  const isAuthed = useIsAuthed()
  const path = isAuthed ? '/auth/dashboard' : '/public/dashboard'
  return (
    <Link as="/dashboard" href={path}>
      Dashboard
    </Link>
  )
}

Versionshistorie