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>
}
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:
Prop | Beispiel | Typ | Erforderlich |
---|---|---|---|
href | href="/dashboard" | String oder Objekt | Ja |
replace | replace={false} | Boolean | - |
scroll | scroll={false} | Boolean | - |
prefetch | prefetch={false} | Boolean | - |
legacyBehavior | legacyBehavior={true} | Boolean | - |
passHref | passHref={true} | Boolean | - |
shallow | shallow={false} | Boolean | - |
locale | locale="fr" | String oder Boolean | - |
onNavigate | onNavigate={(e) => {}} | Funktion | - |
Gut zu wissen: Attribute des
<a>
-Tags wieclassName
odertarget="_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>
)
}
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 ist 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 Home() {
return (
<Link href="/dashboard" replace>
Dashboard
</Link>
)
}
import Link from 'next/link'
export default function Home() {
return (
<Link href="/dashboard" replace>
Dashboard
</Link>
)
}
scroll
Standardwert ist true
. Das Standard-Scrollverhalten von <Link>
in Next.js ist die Beibehaltung der Scrollposition, ähnlich wie Browser das Zurück- und Vorwärtsnavigieren handhaben. Wenn Sie zu einer neuen Page navigieren, bleibt die Scrollposition erhalten, solange die Page im Viewport sichtbar ist. Falls die Page nicht im Viewport sichtbar ist, scrollt Next.js zum obersten Element der Page.
Wenn scroll = {false}
, versucht Next.js nicht, zum ersten Page-Element zu scrollen.
Gut zu wissen: Next.js prüft
scroll: false
, bevor es das Scrollverhalten steuert. Wenn das Scrollen aktiviert ist, identifiziert es das relevante DOM-Element 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 klebender Positionierung und nicht sichtbaren Elementen, die mitgetBoundingClientRect
berechnet wurden. 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>
)
}
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 ihre Daten im Hintergrund, um die Leistung der clientseitigen Navigation zu verbessern. Prefetching ist nur in der Produktion aktiviert.
Folgende Werte können an die prefetch
-Prop übergeben werden:
true
(Standard): Die vollständige Route und ihre Daten werden geprefetched.false
: Prefetching erfolgt nicht beim Eintritt in den Viewport, aber beim Hover. Wenn Sie das Prefetching komplett 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>
)
}
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 aus Kompatibilitätsgründen das alte Verhalten benötigen, können Sie die legacyBehavior
-Prop hinzufügen.
Gut zu wissen: Wenn
legacyBehavior
nicht auftrue
gesetzt ist, können alleanchor
-Tag-Eigenschaften wieclassName
,onClick
usw. auch annext/link
übergeben werden.
passHref
Erzwingt, dass Link
die href
-Property 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>
)
}
import Link from 'next/link'
export default function Home() {
return (
<Link href="/dashboard" shallow={false}>
Dashboard
</Link>
)
}
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.
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>
</>
)
}
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 erhält 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('Navigating...')
// Optional Navigation abbrechen
// e.preventDefault()
}}
>
Dashboard
</Link>
)
}
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('Navigating...')
// Optional Navigation abbrechen
// e.preventDefault()
}}
>
Dashboard
</Link>
)
}
Gut zu wissen: Obwohl
onClick
undonNavigate
ähnlich erscheinen, dienen sie unterschiedlichen Zwecken.onClick
wird für alle Klick-Events ausgeführt, währendonNavigate
nur während der clientseitigen Navigation läuft. Einige wichtige Unterschiede:
- Bei Verwendung von Modifizierertasten (
Strg
/Cmd
+ Klick) wirdonClick
ausgeführt, aberonNavigate
nicht, 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 mitonClick
, aber nicht mitonNavigate
, 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>
)
}
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ächtigt und sich möglicherweise auf die SEO auswirkt. Wenn Sie ESLint verwenden, gibt es eine integrierte Regel next/link-passhref
, um die korrekte Verwendung von passHref
sicherzustellen.
- Wenn Sie die JSX-Pragma-Funktion (
@jsx jsx
) von emotion verwenden, müssen SiepassHref
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
einwickeln:
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 einzuwickeln
const ForwardedMyButton = React.forwardRef(MyButton)
export default function Home() {
return (
<Link href="/about" passHref legacyBehavior>
<ForwardedMyButton />
</Link>
)
}
import Link from 'next/link'
import React from 'react'
// `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}>
Click Me
</a>
)
})
// Fügen Sie einen Anzeigenamen für die Komponente hinzu (nützlich für Debugging)
MyButton.displayName = 'MyButton'
export default function Home() {
return (
<Link href="/about" passHref legacyBehavior>
<MyButton />
</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' },
}}
>
Über uns
</Link>
</li>
<li>
<Link
href={{
pathname: '/blog/[slug]',
query: { slug: 'my-post' },
}}
>
Blog-Beitrag
</Link>
</li>
</ul>
)
}
export default Home
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' },
}}
>
Blog-Beitrag
</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 Eigenschaft verwenden, wie in der Node.js URL-Modul-Dokumentation definiert.
URL ersetzen statt hinzufügen
Das Standardverhalten der Link
-Komponente besteht darin, eine neue URL in den history
-Stack zu push
. 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>
Über uns
</Link>
)
}
import Link from 'next/link'
export default function Home() {
return (
<Link href="/about" replace>
Über uns
</Link>
)
}
Scrollen zum Seitenanfang deaktivieren
Das Standardverhalten von Link
ist das Scrollen zum Seitenanfang. Wenn ein Hash definiert ist, scrollt es zur spezifischen ID, wie ein normales <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>
)
}
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))
}
}
}
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 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>
)
}
'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
- undhref
-Props anpassen. Beispiel: Wenn Sie 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]">Profile</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:
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>
)
}
'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>
)
}
'use client'
import Link from 'next/link'
import { useNavigationBlocker } from '../contexts/navigation-blocker'
export function CustomLink({ children, ...props }) {
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:
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>
)
}
import { NavigationBlockerProvider } from './contexts/navigation-blocker'
export default function RootLayout({ children }) {
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>
)
}
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
Version | Änderungen |
---|---|
v15.3.0 | onNavigate -API hinzugefügt |
v13.0.0 | Benötigt kein untergeordnetes <a> -Tag mehr. Ein Codemod wird bereitgestellt, um Ihre Codebasis automatisch zu aktualisieren. |
v10.0.0 | href -Props, die auf eine dynamische Route verweisen, werden automatisch aufgelöst und benötigen keine as -Prop mehr. |
v8.0.0 | Verbesserte Prefetching-Leistung. |
v1.0.0 | next/link eingeführt. |