Menu

layout.js

Die layout-Datei wird verwendet, um ein Layout in Ihrer Next.js-Anwendung zu definieren.

app/dashboard/layout.tsx
TypeScript
export default function DashboardLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return <section>{children}</section>
}

Ein Root-Layout ist das oberste Layout im Root-Verzeichnis app. Es wird verwendet, um die <html>- und <body>-Tags sowie andere global geteilte UI-Elemente zu definieren.

app/layout.tsx
TypeScript
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

Referenz

Props

children (erforderlich)

Layout-Komponenten sollten eine children-Prop akzeptieren und verwenden. Während des Renderns wird children mit den Routensegmenten gefüllt, die das Layout umschließt. Dies sind hauptsächlich die Komponente eines untergeordneten Layouts (falls vorhanden) oder Seite, könnte aber auch andere spezielle Dateien wie Laden oder Fehler umfassen.

params (optional)

Ein Promise, das zu einem Objekt auflöst, das die dynamischen Routenparameter vom Root-Segment bis zu diesem Layout enthält.

app/dashboard/[team]/layout.tsx
TypeScript
export default async function Layout({
  params,
}: {
  params: Promise<{ team: string }>
}) {
  const team = (await params).team
}
Beispiel-RouteURLparams
app/dashboard/[team]/layout.js/dashboard/1Promise<{ team: '1' }>
app/shop/[tag]/[item]/layout.js/shop/1/2Promise<{ tag: '1', item: '2' }>
app/blog/[...slug]/layout.js/blog/1/2Promise<{ slug: ['1', '2'] }>
  • Da die params-Prop ein Promise ist, müssen Sie async/await oder React's use-Funktion verwenden, um die Werte zu erhalten.
    • In Version 14 und früher war params eine synchrone Prop. Um die Abwärtskompatibilität zu unterstützen, können Sie in Next.js 15 noch synchron darauf zugreifen, aber dieses Verhalten wird in Zukunft veraltet sein.

Root-Layouts

Das app-Verzeichnis muss ein Root-layout.js enthalten.

app/layout.tsx
TypeScript
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html>
      <body>{children}</body>
    </html>
  )
}
  • Das Root-Layout muss <html>- und <body>-Tags definieren.
    • Sie sollten <head>-Tags wie <title> und <meta> nicht manuell zu Root-Layouts hinzufügen. Verwenden Sie stattdessen die Metadata-API, die automatisch fortgeschrittene Anforderungen wie Streaming und De-Duplizierung von <head>-Elementen handhabt.
  • Sie können Routengruppen verwenden, um mehrere Root-Layouts zu erstellen.
    • Die Navigation zwischen mehreren Root-Layouts verursacht einen vollständigen Seitenneuladen (im Gegensatz zur clientseitigen Navigation). Zum Beispiel führt die Navigation von /cart mit app/(shop)/layout.js zu /blog mit app/(marketing)/layout.js zu einem vollständigen Seitenneuladen. Dies gilt nur für mehrere Root-Layouts.

Einschränkungen

Layouts erhalten keine searchParams

Im Gegensatz zu Seiten erhalten Layout-Komponenten die searchParams-Prop nicht. Dies liegt daran, dass ein gemeinsames Layout während der Navigation nicht neu gerendert wird, was zu veralteten searchParams zwischen Navigationen führen könnte.

Bei clientseitiger Navigation rendert Next.js automatisch nur den Teil der Seite unter dem gemeinsamen Layout zwischen zwei Routen.

Zum Beispiel wird in der folgenden Verzeichnisstruktur dashboard/layout.tsx das gemeinsame Layout für /dashboard/settings und /dashboard/analytics:

Dateistruktur mit einem Dashboard-Ordner, der eine layout.tsx-Datei enthält, und settings- und analytics-Ordnern mit ihren eigenen Seiten

Bei der Navigation von /dashboard/settings zu /dashboard/analytics wird page.tsx in /dashboard/analytics auf dem Server neu gerendert, während dashboard/layout.tsx nicht neu gerendert wird, da es eine gemeinsame UI zwischen den beiden Routen ist.

Diese Leistungsoptimierung ermöglicht eine schnellere Navigation zwischen Seiten, die ein Layout teilen, da nur das Datenabrufen und -rendering für die Seite ausgeführt werden muss, anstatt der gesamten Route, die möglicherweise gemeinsame Layouts enthält, die ihre eigenen Daten abrufen.

Da dashboard/layout.tsx nicht neu gerendert wird, kann die searchParams-Prop in der Layout-Serverkomponente nach der Navigation veraltet sein.

Verwenden Sie stattdessen die Seiten-searchParams-Prop oder den useSearchParams-Hook in einer Client-Komponente innerhalb des Layouts, die auf dem Client mit den aktuellen searchParams neu gerendert wird.

Layouts können nicht auf pathname zugreifen

Layouts können nicht auf pathname zugreifen. Dies liegt daran, dass Layouts standardmäßig Serverkomponenten sind und während der clientseitigen Navigation nicht neu gerendert werden, was zu veralteten pathname zwischen Navigationen führen könnte. Um Veraltung zu verhindern, müsste Next.js alle Segmente einer Route neu abrufen, wodurch die Vorteile des Cachings verloren gehen und die RSC-Nutzlast bei der Navigation zunimmt.

Stattdessen können Sie die Logik, die von pathname abhängt, in eine Client-Komponente auslagern und in Ihre Layouts importieren. Da Client-Komponenten während der Navigation neu gerendert (aber nicht neu abgerufen) werden, können Sie Next.js-Hooks wie usePathname verwenden, um den aktuellen Pfadnamen zu erhalten und Veraltung zu verhindern.

app/dashboard/layout.tsx
TypeScript
import { ClientComponent } from '@/app/ui/ClientComponent'
 
export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <>
      <ClientComponent />
      {/* Andere Layout-UI */}
      <main>{children}</main>
    </>
  )
}

Häufige pathname-Muster können auch mit der params-Prop implementiert werden.

Weitere Informationen finden Sie im Beispiele-Abschnitt.

Beispiele

Anzeigen von Inhalt basierend auf params

Mit dynamischen Routensegmenten können Sie spezifische Inhalte basierend auf der params-Eigenschaft anzeigen oder abrufen.

app/dashboard/layout.tsx
TypeScript
export default async function DashboardLayout({
  children,
  params,
}: {
  children: React.ReactNode
  params: Promise<{ team: string }>
}) {
  const { team } = await params
 
  return (
    <section>
      <header>
        <h1>Willkommen zum Dashboard von {team}</h1>
      </header>
      <main>{children}</main>
    </section>
  )
}

Auslesen von params in Client-Komponenten

Um params in einer Client-Komponente zu verwenden (die nicht async sein kann), können Sie die React-Funktion use zum Auslesen des Promises verwenden:

app/page.tsx
TypeScript
'use client'
 
import { use } from 'react'
 
export function Page({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = use(params)
}
app/page.js
'use client'
 
import { use } from 'react'
 
export function Page({ params }) {
  const { slug } = use(params)
}

Versionshistorie

VersionÄnderungen
v15.0.0-RCparams ist jetzt ein Promise. Ein Codemod ist verfügbar.
v13.0.0layout eingeführt.