Übersicht über ASP.NET Core Blazor Formulare

In diesem Artikel wird erläutert, wie Formulare in Blazor verwendet werden können.

Eingabekomponenten und Formulare

Das Blazor-Framework unterstützt Formulare und bietet integrierte Eingabekomponenten:

• Gebunden an ein Objekt oder Modell, das Datenanmerkungen verwenden kann
  • HTML-Formulare mit dem <form>-Element
  • EditForm-Komponenten
• Integrierte Eingabekomponenten

Der Namespace Microsoft.AspNetCore.Components.Forms bietet Folgendes:

• Klassen zum Verwalten von Formularelementen, Zustand und Validierung.
• Zugriff auf integrierte Input*-Komponenten.

Ein aus der Blazor-Projektvorlage erstelltes Projekt enthält standardmäßig den Namespace in der _Imports.razor-Datei der App, wodurch der Namespace den Razor-Komponenten der App zur Verfügung steht.

Standard-HTML-Formulare werden unterstützt. Erstellen Sie ein Formular mit dem normalen HTML-Tag <form>, und geben Sie einen @onsubmit-Handler für die Verarbeitung der übermittelten Formularanforderung an.

StarshipPlainForm.razor:

@page "/starship-plain-form"
@inject ILogger<StarshipPlainForm> Logger

<form method="post" @onsubmit="Submit" @formname="starship-plain-form">
    <AntiforgeryToken />
    <div>
        <label>
            Identifier: 
            <InputText @bind-Value="Model!.Id" />
        </label>
    </div>
    <div>
        <button type="submit">Submit</button>
    </div>
</form>

@code {
    [SupplyParameterFromForm]
    public Starship? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private void Submit()
    {
        Logger.LogInformation("Id = {Id}", Model?.Id);
    }

    public class Starship
    {
        public string? Id { get; set; }
    }
}

In der vorherigen StarshipPlainForm-Komponente:

• Das Formular dort gerendert, wo das <form>-Element erscheint. Das Formular wird mit dem @formname Direktiven-Attribut benannt, das das Formular eindeutig für das Blazor Framework identifiziert.
• Das Modell wird im @code-Block der Komponente erstellt und in einer öffentlichen Eigenschaft (Model) gespeichert. Das Attribut [SupplyParameterFromForm] gibt an, dass der Wert der zugeordneten Eigenschaft aus den Formulardaten bereitgestellt werden soll. Daten in der Anforderung, die dem Namen der Eigenschaft entsprechen, werden an die Eigenschaft gebunden.
• Die InputText-Komponente ist eine Eingabekomponente zum Bearbeiten von Zeichenfolgenwerten. Das @bind-Value-Anweisungsattribut bindet die Model.Id-Modelleigenschaft an die Value-Eigenschaft der InputText-Komponente.
• Die Methode Submit wird als Handler für den @onsubmit-Rückruf registriert. Der Handler wird aufgerufen, wenn das Formular vom Benutzer übermittelt wird.

Wichtig

Verwenden Sie immer das @formname Direktive-Attribut mit einem eindeutigen Formularnamen.

Blazor verbessert die Seitennavigation und Formularverarbeitung, indem die Anforderung abgefangen wird, um die Antwort auf das vorhandene Dokumentobjektmodell (DOM) anzuwenden, wobei ein möglichst großer Teil des gerenderten Formulars erhalten bleibt. Durch diese Verbesserung entfällt die Notwendigkeit, die Seite vollständig zu laden, was zu einem wesentlich reibungsloseren Benutzererlebnis führt, ähnlich wie eine Single-Page-App (SPA), obwohl die Komponente auf dem Server gerendert wird. Weitere Informationen finden Sie unter ASP.NET Core: Routing und Navigation in Blazor.

Das Streamingrendering wird für einfache HTML-Formulare unterstützt.

Hinweis

Dokumentationslinks zur .NET-Referenzquelle laden in der Regel den Standardbranch des Repositorys, der die aktuelle Entwicklung für das nächste Release von .NET darstellt. Um ein Tag für ein bestimmtes Release auszuwählen, wählen Sie diesen mit der Dropdownliste Switch branches or tags (Branches oder Tags wechseln) aus. Weitere Informationen finden Sie unter How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205) (Auswählen eines Versionstags von ASP.NET Core-Quellcode (dotnet/AspNetCore.Docs #26205)).

Das vorstehende Beispiel beinhaltet Unterstützung der Fälschungssicherheit, indem eine AntiforgeryToken-Komponente in das Formular aufgenommen wird. Die Unterstützung der Fälschungssicherheit wird im Abschnitt Unterstützung der Fälschungssicherheit in diesem Artikel näher erläutert.

Verwenden Sie JavaScript, um ein Formular zu übermitteln (submit (MDN-Dokumentation)), das auf den DOM-Ereignissen eines anderen Elements basiert, beispielsweise auf oninput oder onblur.

Anstatt einfache Formulare in Blazor-Apps zu verwenden, wird ein Formular in der Regel mit der integrierten Formularunterstützung von Blazor mithilfe der Frameworkkomponente EditForm definiert. Die folgende Razor-Komponente veranschaulicht typische Elemente, Komponenten und Razor-Code zum Rendern eines Webformulars mithilfe einer EditForm-Komponente.

Starship1.razor:

@page "/starship-1"
@inject ILogger<Starship1> Logger

<EditForm Model="Model" OnSubmit="Submit" FormName="Starship1">
    <div>
        <label>
            Identifier:
            <InputText @bind-Value="Model!.Id" />
        </label>
    </div>
    <div>
        <button type="submit">Submit</button>
    </div>
</EditForm>

@code {
    [SupplyParameterFromForm]
    public Starship? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private void Submit()
    {
        Logger.LogInformation("Id = {Id}", Model?.Id);
    }

    public class Starship
    {
        public string? Id { get; set; }
    }
}

In der vorherigen Starship1-Komponente:

• Die EditForm-Komponente dort gerendert, wo das <EditForm>-Element steht. Das Formular wird mit dem @formname Direktiven-Attribut benannt, das das Formular eindeutig für das Blazor Framework identifiziert.
• Das Modell wird im @code-Block der Komponente erstellt und in einer öffentlichen Eigenschaft (Model) gespeichert. Die Eigenschaft wird dem EditForm.Model-Parameter zugewiesen. Das Attribut [SupplyParameterFromForm] gibt an, dass der Wert der zugeordneten Eigenschaft aus den Formulardaten bereitgestellt werden soll. Daten in der Anforderung, die dem Namen der Eigenschaft entsprechen, werden an die Eigenschaft gebunden.
• Die InputText-Komponente ist eine Eingabekomponente zum Bearbeiten von Zeichenfolgenwerten. Das @bind-Value-Anweisungsattribut bindet die Model.Id-Modelleigenschaft an die Value-Eigenschaft der InputText-Komponente.
• Die Methode Submit wird als Handler für den OnSubmit-Rückruf registriert. Der Handler wird aufgerufen, wenn das Formular vom Benutzer übermittelt wird.

Wichtig

Verwenden Sie immer das @formname Direktive-Attribut mit einem eindeutigen Formularnamen.

Blazor verbessert die Seitennavigation und die Handhabung von Formularen für EditForm-Komponenten. Weitere Informationen finden Sie unter ASP.NET Core: Routing und Navigation in Blazor.

Das Streamingrendering wird für EditForm unterstützt.

Hinweis

Dokumentationslinks zur .NET-Referenzquelle laden in der Regel den Standardbranch des Repositorys, der die aktuelle Entwicklung für das nächste Release von .NET darstellt. Um ein Tag für ein bestimmtes Release auszuwählen, wählen Sie diesen mit der Dropdownliste Switch branches or tags (Branches oder Tags wechseln) aus. Weitere Informationen finden Sie unter How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205) (Auswählen eines Versionstags von ASP.NET Core-Quellcode (dotnet/AspNetCore.Docs #26205)).

Weitere Informationen zur Eigenschaftenbindung finden Sie unter Blazor-Datenbindung in ASP.NET Core.

Im nächsten Beispiel wird die vorherige Komponente so geändert, dass das Formular in der Starship2-Komponente erstellt wird:

• OnSubmit wird durch OnValidSubmit ersetzt. Dadurch wird der zugewiesene Ereignishandler verarbeitet, wenn das Formular bei Übermittlung durch den Benutzer gültig ist.
• Eine ValidationSummary-Komponente wird hinzugefügt, um Validierungsmeldungen anzuzeigen, wenn das Formular bei der Formularübermittlung ungültig ist.
• Das Datenanmerkungs-Validierungssteuerelement (DataAnnotationsValidator-Komponente†) fügt Validierungsunterstützung mithilfe von Datenkommentaren hinzu:
  • Wenn das Formularfeld <input> leer gelassen wird, wenn die Schaltfläche Submit ausgewählt ist, wird in der Validierungszusammenfassung (ValidationSummary-Komponente‡) ein Fehler angezeigt („The Id field is required.“), und Submit wird nicht aufgerufen.
  • Wenn das Formularfeld <input> bei ausgewählter Schaltfläche Submit mehr als 10 Zeichen enthält, wird in der Validierungszusammenfassung ein Fehler angezeigt („Id is too long.“). Submit wird nicht aufgerufen.
  • Wenn das Formularfeld <input> bei ausgewählter Schaltfläche Submit einen gültigen Wert enthält, wird Submit aufgerufen.

†Die DataAnnotationsValidator-Komponente wird im Abschnitt Validierungssteuerelement-Komponente behandelt. ‡Die ValidationSummary-Komponente wird im Abschnitt Komponenten der Validierungszusammenfassung und der Validierungsnachricht behandelt.

Starship2.razor:

@page "/starship-2"
@using System.ComponentModel.DataAnnotations
@inject ILogger<Starship2> Logger

<EditForm Model="Model" OnValidSubmit="Submit" FormName="Starship2">
    <DataAnnotationsValidator />
    <ValidationSummary />
    <label>
        Identifier: 
        <InputText @bind-Value="Model!.Id" />
    </label>
    <button type="submit">Submit</button>
</EditForm>

@code {
    [SupplyParameterFromForm]
    public Starship? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private void Submit()
    {
        Logger.LogInformation("Id = {Id}", Model?.Id);
    }

    public class Starship
    {
        [Required]
        [StringLength(10, ErrorMessage = "Id is too long.")]
        public string? Id { get; set; }
    }
}

Behandeln von Formularübermittlungen

Das EditForm stellt die folgenden Rückrufe für die Behandlung der Formularübermittlung bereit:

• Verwenden Sie OnValidSubmit, um einen Ereignishandler zuzuweisen, der ausgeführt wird, wenn ein Formular mit gültigen Feldern übermittelt wird.
• Verwenden Sie OnInvalidSubmit, um einen Ereignishandler zuzuweisen, der ausgeführt wird, wenn ein Formular mit ungültigen Feldern übermittelt wird.
• Verwenden Sie OnSubmit, um einen Ereignishandler zuzuweisen, der unabhängig vom Validierungsstatus der Formularfelder ausgeführt wird. Das Formular wird überprüft, indem EditContext.Validate in der Ereignishandlermethode aufgerufen wird. Wenn Validatetrue zurückgibt, ist das Formular gültig.

Löschen eines Formulars oder Felds

Setzen Sie ein Formular zurück, indem Sie das Modell wieder auf den Standardzustand zurücksetzen. Dies ist innerhalb oder außerhalb des Markups von EditForm möglich:

<button @onclick="ClearForm">Clear form</button>

...

private void ClearForm() => Model = new();

Verwenden Sie alternativ einen expliziten Razor-Ausdruck:

<button @onclick="@(() => Model = new())">Clear form</button>

Setzen Sie ein Feld zurück, indem Sie den Modellwert auf den Standardzustand zurücksetzen:

<button @onclick="ResetId">Reset Identifier</button>

...

private void ResetId() => Model!.Id = string.Empty;

Verwenden Sie alternativ einen expliziten Razor-Ausdruck:

<button @onclick="@(() => Model!.Id = string.Empty)">Reset Identifier</button>

Es ist nicht erforderlich, in den vorherigen Beispielen StateHasChanged aufzurufen, da StateHasChanged automatisch vom Blazor-Framework aufgerufen wird, um die Komponente erneut zu rendern, nachdem ein Ereignishandler aufgerufen wurde. Wenn zum Aufrufen der Methoden für das Leeren eines Formulars oder Felds kein Ereignishandler verwendet wird, sollte im Code StateHasChanged aufgerufen werden, um die Komponente erneut zu rendern.

Unterstützung des Schutzes vor Fälschung

Antiforgery-Dienste werden Blazor-Apps automatisch hinzugefügt, wenn AddRazorComponents in der Datei Program aufgerufen wird.

Die App verwendet Antiforgery-Middleware, indem UseAntiforgery in der Datei Program innerhalb der Pipeline zur Anforderungsverarbeitung aufgerufen wird. UseAntiforgery wird nach dem Aufruf von UseRouting aufgerufen. Wenn Anrufe von UseRouting und UseEndpoints vorhanden, muss der Aufruf von UseAntiforgery zwischen diesen liegen. Der Aufruf von UseAntiforgery muss nach den Aufrufen von UseAuthentication und UseAuthorization erfolgen.

Die AntiforgeryToken-Komponente rendert ein Token für den Fälschungsschutz als verborgenes Feld, und das [RequireAntiforgeryToken]-Attribut aktiviert den Schutz. Wenn eine Überprüfung des Fälschungsschutzes einen Fehler zurückgibt, wird eine 400 - Bad Request-Antwort ausgelöst, und das Formular wird nicht verarbeitet.

Bei auf EditForm basierenden Formularen werden die Komponente AntiforgeryToken und das Attribut [RequireAntiforgeryToken] automatisch hinzugefügt, um standardmäßig einen Schutz vor Fälschung bereitzustellen.

Fügen Sie Formularen, die auf dem HTML-Element <form> basieren, die AntiforgeryToken-Komponente manuell hinzu:

<form method="post" @onsubmit="Submit" @formname="starshipForm">
    <AntiforgeryToken />
    <input id="send" type="submit" value="Send" />
</form>

@if (submitted)
{
    <p>Form submitted!</p>
}

@code{
    private bool submitted = false;

    private void Submit() => submitted = true;
}

Warnung

Bei Formularen, die auf EditForm oder dem HTML-Element <form> basieren, kann der Fälschungsschutz deaktiviert werden, indem required: false an das Attribut [RequireAntiforgeryToken] übergeben wird. Das folgende Beispiel deaktiviert den Fälschungsschutz und wird für öffentliche Apps nicht empfohlen:

@using Microsoft.AspNetCore.Antiforgery
@attribute [RequireAntiforgeryToken(required: false)]

Weitere Informationen hierzu finden Sie unter Authentifizierung und Autorisierung in ASP.NET Core Blazor.

Erweiterte Formularverarbeitung

Erweiterte Navigation für POST-Anforderungen von Formularen mit dem Enhance-Parameter für EditForm-Formulare oder dem data-enhance-Attribut für HTML-Formulare (<form>):

<EditForm ... Enhance ...>
    ...
</EditForm>

<form ... data-enhance ...>
    ...
</form>

❌Nicht unterstützt: Sie können die erweiterte Navigation im Vorgängerelement eines Formulars nicht festlegen, um die erweiterte Formularverarbeitung zu aktivieren.

<div ... data-enhance ...>
    <form ...>
        <!-- NOT enhanced -->
    </form>
</div>

Erweiterte Formularbeiträge funktionieren nur mit Blazor-Endpunkten. Das Bereitstellen eines erweiterten Formulars an einen Nicht-Blazor-Endpunkt führt zu einem Fehler.

So deaktivieren Sie die erweiterte Formularverarbeitung:

• Entfernen Sie für ein EditForm-Formular den Parameter Enhance aus dem Formularelement (oder legen Sie diesen auf false fest: Enhance="false").
• Entfernen Sie für einen <form>-HTML-Element den Parameter data-enhance aus dem Formularelement (oder legen Sie diesen auf false fest: data-enhance="false").

Die erweiterte Navigation und Formularverarbeitung von Blazor können dynamische Änderungen am Dokumentobjektmodell (DOM) rückgängig machen, wenn der aktualisierte Inhalt nicht Teil des Serverrenderings ist. Verwenden Sie das data-permanent-Attribut, um den Inhalt eines Elements beizubehalten.

Im folgenden Beispiel wird der Inhalt des <div>-Elements dynamisch durch ein Skript aktualisiert, wenn die Seite geladen wird:

<div data-permanent>
    ...
</div>

Informationen zum globalen Deaktivieren der erweiterten Navigation und Formularverarbeitung finden Sie unter ASP.NET Core Blazor-Start.

Einen Leitfaden zur Verwendung des enhancedload-Ereignisses, um nach erweiterter Seitenupdates zu lauschen, finden Sie unter Routing und Navigation in ASP.NET Core Blazor.

Beispiele

Beispiele übernehmen keine erweiterte Formularverarbeitung für POST-Anforderungen von Formularen, jedoch können alle Beispiele aktualisiert werden, um die erweiterten Features zu übernehmen. Befolgen Sie hierzu den Leitfaden im Abschnitt Erweiterte Formularverarbeitung.

Um zu veranschaulichen, wie Formulare mit Überprüfung von Datenanmerkungen funktionieren, verwenden die Beispielkomponenten die System.ComponentModel.DataAnnotations-API. Wenn Sie eine zusätzliche Codezeile in Komponenten vermeiden möchten, die Datenanmerkungen verwenden, stellen Sie den Namespace in den Komponenten der App mit der Importdatei zur Verfügung (_Imports.razor):

@using System.ComponentModel.DataAnnotations

Die Formularbeispiele beziehen sich auf Aspekte des Star Trek-Universums. Star Trek ist eine Marke von CBS Studios und Paramount mit Copyright ©1966-2023.

Zusätzliche Ressourcen

• Blazor-Dateiuploads in ASP.NET Core
• GitHub-Repository mit Blazor-Beispielen (dotnet/blazor-samples) (Informationen zum Herunterladen)
• Testassets für Formulare im ASP.NET Core GitHub-Repository (dotnet/aspnetcore)