<Form>

Die <Form>-Komponente erweitert das HTML-<form>-Element, um Prefetching der Lade-UI, Client-seitige Navigation bei der Übermittlung und progressiven Enhancement bereitzustellen.

Sie ist nützlich für Formulare, die URL-Suchparameter aktualisieren, da sie den Boilerplate-Code reduziert, der benötigt wird, um die oben genannten Funktionen zu erreichen.

Grundlegende Verwendung:

import Form from 'next/form'
 
export default function Page() {
  return (
    <Form action="/search">
      {/* Bei der Übermittlung wird der Eingabewert an die URL angehängt, 
          z.B. /search?query=abc */}
      <input name="query" />
      <button type="submit">Absenden</button>
    </Form>
  )
}

Referenz

Das Verhalten der <Form>-Komponente hängt davon ab, ob der action-Prop eine string oder function übergeben wird.

• Wenn action eine Zeichenkette ist, verhält sich die <Form> wie ein natives HTML-Formular, das eine GET-Methode verwendet. Die Formulardaten werden als Suchparameter in die URL codiert, und bei der Übermittlung wird zur angegebenen URL navigiert. Zusätzlich führt Next.js Folgendes aus:
  • Prefetching des Pfads, wenn das Formular sichtbar wird. Dies lädt gemeinsame Benutzeroberfläche (z.B. layout.js und loading.js) vor und führt zu schnellerer Navigation.
  • Führt eine Client-seitige Navigation anstelle eines vollständigen Seitenneulades durch, wenn das Formular übermittelt wird. Dabei bleibt die gemeinsame Benutzeroberfläche und der Client-seitige Zustand erhalten.
• Wenn action eine Funktion (Server-Aktion) ist, verhält sich <Form> wie ein React-Formular und führt die Aktion bei der Formularübermittlung aus.

action (Zeichenkette) Props

Wenn action eine Zeichenkette ist, unterstützt die <Form>-Komponente die folgenden Props:

• action: Die URL oder der Pfad, zu dem bei der Formularübermittlung navigiert wird.
  • Eine leere Zeichenkette "" navigiert zur gleichen Route mit aktualisierten Suchparametern.
• replace: Ersetzt den aktuellen Historienzustand, anstatt einen neuen zum Browser-Verlaufsstapel hinzuzufügen. Standard ist false.
• scroll: Steuert das Scroll-Verhalten während der Navigation. Standard ist true, was bedeutet, dass zur Spitze der neuen Route gescrollt wird und die Scroll-Position für Rückwärts- und Vorwärtsnavigation beibehalten wird.
• prefetch: Steuert, ob der Pfad prefetched werden soll, wenn das Formular im Viewport des Benutzers sichtbar wird. Standard ist true.

action (Funktion) Props

Wenn action eine Funktion ist, unterstützt die <Form>-Komponente die folgenden Prop:

• action: Die Server-Aktion, die bei der Formularübermittlung aufgerufen wird. Weitere Informationen in den React-Dokumenten.

Hinweis: Wenn action eine Funktion ist, werden die Props replace und scroll ignoriert.

Einschränkungen

• formAction: Kann in <button> oder <input type="submit"> verwendet werden, um den action-Prop zu überschreiben. Next.js führt eine Client-seitige Navigation durch, diese Methode unterstützt jedoch kein Prefetching.
  • Bei Verwendung von basePath müssen Sie es auch im formAction-Pfad einschließen, z.B. formAction="/base-path/search".
• key: Das Übergeben eines key-Props an eine Zeichenketten-action wird nicht unterstützt. Wenn Sie eine erneute Darstellung auslösen oder eine Mutation durchführen möchten, verwenden Sie stattdessen eine Funktions-action.

• onSubmit: Kann verwendet werden, um die Logik zur Formulareinreichung zu handhaben. Wenn jedoch event.preventDefault() aufgerufen wird, überschreibt dies das Verhalten von <Form>, wie z.B. das Navigieren zur angegebenen URL.
• method, encType, target: Werden nicht unterstützt, da sie das Verhalten von <Form> überschreiben.
  • Entsprechend können formMethod, formEncType und formTarget verwendet werden, um die Eigenschaften method, encType und target zu überschreiben. Die Verwendung dieser Eigenschaften greift auf das native Browserverhalten zurück.
  • Wenn Sie diese Eigenschaften verwenden müssen, nutzen Sie stattdessen das HTML-Element <form>.
• <input type="file">: Bei Verwendung dieses Eingabetyps, wenn action eine Zeichenfolge ist, entspricht das Verhalten dem des Browsers, indem der Dateiname anstelle des Dateiobjekts übermittelt wird.

Beispiele

Suchformular, das zu einer Suchergebnisseite führt

Sie können ein Suchformular erstellen, das zu einer Suchergebnisseite navigiert, indem Sie den Pfad als action übergeben:

import Form from 'next/form'
 
export default function Page() {
  return (
    <Form action="/search">
      <input name="query" />
      <button type="submit">Absenden</button>
    </Form>
  )
}

Wenn der Benutzer das Abfrageeingabefeld aktualisiert und das Formular absendet, werden die Formulardaten als Suchparameter in die URL kodiert, z.B. /search?query=abc.

Hinweis: Wenn Sie einen leeren String "" an action übergeben, navigiert das Formular zur gleichen Route mit aktualisierten Suchparametern.

Auf der Ergebnisseite können Sie die Abfrage mithilfe der searchParams page.js-Eigenschaft abrufen und zur Datenabfrage aus einer externen Quelle verwenden.

import { getSearchResults } from '@/lib/search'
 
export default async function SearchPage({
  searchParams,
}: {
  searchParams: { [key: string]: string | string[] | undefined }
}) {
  const results = await getSearchResults(searchParams.query)
 
  return <div>...</div>
}

Wenn <Form> im Sichtfeld des Benutzers sichtbar wird, werden gemeinsame Benutzeroberflächen (wie layout.js und loading.js) auf der /search-Seite vorab abgerufen. Bei der Übermittlung navigiert das Formular sofort zur neuen Route und zeigt die Ladebenutzeroberfläche an, während die Ergebnisse abgerufen werden. Sie können die Fallback-Benutzeroberfläche mit loading.js gestalten:

export default function Loading() {
  return <div>Wird geladen...</div>
}

Um Fälle abzudecken, in denen die gemeinsame Benutzeroberfläche noch nicht geladen wurde, können Sie dem Benutzer sofortiges Feedback geben, indem Sie useFormStatus verwenden.

Erstellen Sie zunächst eine Komponente, die einen Ladezustand anzeigt, wenn das Formular in Bearbeitung ist:

'use client'
import { useFormStatus } from 'react-dom'
 
export default function SearchButton() {
  const status = useFormStatus()
  return (
    <button type="submit">{status.pending ? 'Suche läuft...' : 'Suchen'}</button>
  )
}

Aktualisieren Sie dann die Suchformularseite, um die SearchButton-Komponente zu verwenden:

import Form from 'next/form'
import { SearchButton } from '@/ui/search-button'
 
export default function Page() {
  return (
    <Form action="/search">
      <input name="query" />
      <SearchButton />
    </Form>
  )
}

Mutationen mit Server-Aktionen

Sie können Mutationen durchführen, indem Sie eine Funktion an die action-Eigenschaft übergeben.

import Form from 'next/form'
import { createPost } from '@/posts/actions'
 
export default function Page() {
  return (
    <Form action={createPost}>
      <input name="title" />
      {/* ... */}
      <button type="submit">Beitrag erstellen</button>
    </Form>
  )
}

Nach einer Mutation ist es üblich, zur neuen Ressource weiterzuleiten. Sie können die Funktion redirect aus next/navigation verwenden, um zur neuen Beitragsseite zu navigieren.

Hinweis: Da das "Ziel" der Formularübermittlung erst nach Ausführung der Aktion bekannt ist, kann <Form> die gemeinsame Benutzeroberfläche nicht automatisch vorab abrufen.

'use server'
import { redirect } from 'next/navigation'
 
export async function createPost(formData: FormData) {
  // Neuen Beitrag erstellen
  // ...
 
  // Weiterleitung zum neuen Beitrag
  redirect(`/posts/${data.id}`)
}

Dann können Sie auf der neuen Seite Daten mithilfe der params-Eigenschaft abrufen:

import { getPost } from '@/posts/data'
 
export default async function PostPage({ params }: { params: { id: string } }) {
  const data = await getPost(params.id)
 
  return (
    <div>
      <h1>{data.title}</h1>
      {/* ... */}
    </div>
  )
}

Weitere Beispiele finden Sie in der Dokumentation zu Server-Aktionen.