Omówienie formularzy w ASP.NET Core Blazor

W tym artykule wyjaśniono, jak używać formularzy w programie Blazor.

Składniki wejściowe i formularze

Platforma Blazor obsługuje formularze i udostępnia wbudowane składniki wejściowe:

• Powiązana z obiektem lub modelem, który może używać adnotacji danych.
  • Formularze HTML z elementem <form> .
  • EditForm Składniki.
• Wbudowane składniki wejściowe.

Uwaga

Nieobsługiwane funkcje weryfikacji ASP.NET Core zostały omówione w sekcji Nieobsługiwane funkcje sprawdzania poprawności.

Microsoft.AspNetCore.Components.Forms Przestrzeń nazw zapewnia:

• Klasy do zarządzania elementami formularza, stanem i walidacją.
• Dostęp do wbudowanych Input* składników.

Projekt utworzony na podstawie Blazor szablonu zawiera przestrzeń nazw w pliku aplikacji _Imports.razor, co sprawia, że przestrzeń nazw jest dostępna dla składników aplikacji Razor.

Obsługiwane są standardowe formularze HTML. Utwórz formularz przy użyciu normalnego tagu HTML <form> i określ procedurę @onsubmit obsługi przesłanego żądania formularza.

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]
    private 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; }
    }
}

W poprzednim StarshipPlainForm składniku:

• Formularz jest wyświetlany w miejscu, gdzie pojawia się element <form>. Formularz ma nazwę z atrybutem @formname dyrektywy, który jednoznacznie identyfikuje formularz w Blazor strukturze.
• Model jest tworzony w bloku składnika @code i przechowywany we właściwości publicznej (Model). Atrybut [SupplyParameterFromForm] wskazuje, że wartość skojarzonej właściwości powinna być dostarczana z danych formularza. Dane w żądaniu zgodnym z nazwą właściwości są powiązane z właściwością.
• Składnik InputText jest składnikiem wejściowym do edytowania wartości ciągów. Atrybut @bind-Value dyrektywy wiąże Model.Id właściwość modelu z właściwością InputText składnika Value .
• Metoda Submit jest zarejestrowana jako obsługująca wywołanie zwrotne @onsubmit. Procedura obsługi jest wywoływana po przesłaniu formularza przez użytkownika.

Ważne

Zawsze używaj unikatowej nazwy formularza z atrybutem dyrektywy @formname.

Blazor Ulepsza nawigację na stronie i obsługę formularzy, przechwytując żądanie w celu zastosowania odpowiedzi do istniejącego modelu DOM, zachowując jak najwięcej renderowanego formularza. Rozszerzenie pozwala uniknąć konieczności pełnego załadowania strony i zapewnia znacznie bardziej płynne środowisko użytkownika, podobnie jak aplikacja jednostronicowa (SPA), chociaż składnik jest renderowany na serwerze. Aby uzyskać więcej informacji, zapoznaj się z trasowaniem i nawigacją w ASP.NET CoreBlazor.

Renderowanie strumieniowe jest obsługiwane w przypadku zwykłych formularzy HTML. Należy pamiętać, że podczas POSTtworzenia formularza przesyłane strumieniowo są tylko aktualizacje MODELU DOM wewnątrz procedur obsługi formularza (na przykład @onsubmit). Aktualizacje wewnątrz OnInitializedAsync są przesyłane strumieniowo tylko dla GET żądań. Aby uzyskać więcej informacji, zobacz Pozwalanie na strumieniowe ładowanie odpowiedzi POST (dotnet/aspnetcore #50994).

Uwaga

Linki dokumentacyjne do źródła referencyjnego .NET zwykle ładują domyślną gałąź repozytorium, która odzwierciedla obecne prace rozwojowe nad nadchodzącą wersją .NET. Aby wybrać tag dla określonej wersji, użyj listy rozwijanej Przełącz gałęzie lub tagi. Aby uzyskać więcej informacji, zobacz Jak wybrać tag wersji kodu źródłowego platformy ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Powyższy przykład obejmuje obsługę ochrony antyfałszywkowej, dołączając komponent AntiforgeryToken w formularzu. Pomoc techniczna dotycząca ochrony przed fałszerzami jest bardziej objaśniona w sekcji pomocy technicznej dotyczącej ochrony przed fałszerzami w tym artykule.

Aby przesłać formularz na podstawie zdarzeń DOM innego elementu, na przykład oninput lub onblur, użyj języka JavaScript do przesłania formularza (submit).

Zamiast używać zwykłych formularzy w Blazor aplikacjach, formularz jest zazwyczaj definiowany za pomocą wbudowanej obsługi formularzy Blazor przy użyciu składnika frameworka EditForm. Poniższy Razor komponent przedstawia typowe elementy, komponenty i Razor kod do renderowania formularzy internetowych przy użyciu EditForm komponentu.

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]
    private 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; }
    }
}

W poprzednim Starship1 składniku:

• Składnik EditForm jest renderowany w miejscu, gdzie pojawia się element <EditForm>. Formularz ma nazwę z właściwością FormName, która jednoznacznie identyfikuje formularz w strukturze Blazor.
• Model jest tworzony w bloku składnika @code i przechowywany we właściwości publicznej (Model). Właściwość jest przypisywana do parametru EditForm.Model . Atrybut [SupplyParameterFromForm] wskazuje, że wartość skojarzonej właściwości powinna być dostarczana z danych formularza. Dane w żądaniu zgodnym z nazwą właściwości są powiązane z właściwością.
• Składnik InputText jest składnikiem wejściowym do edytowania wartości ciągów. Atrybut @bind-Value dyrektywy wiąże Model.Id właściwość modelu z właściwością InputText składnika Value .
• Metoda Submit jest zarejestrowana jako obsługa wywołania zwrotnego OnSubmit. Procedura obsługi jest wywoływana po przesłaniu formularza przez użytkownika.

Ważne

Zawsze używaj właściwości FormName z unikatową nazwą formularza.

Blazor Poprawia nawigację po stronie i obsługę formularzy dla EditForm komponentów. Aby uzyskać więcej informacji, zapoznaj się z trasowaniem i nawigacją w ASP.NET CoreBlazor.

Renderowanie strumieniowe jest obsługiwane przez EditForm. Należy pamiętać, że podczas POSTtworzenia formularza przesyłane strumieniowo są tylko aktualizacje MODELU DOM wewnątrz procedur obsługi formularza (na przykład OnValidSubmit). Aktualizacje wewnątrz OnInitializedAsync są przesyłane strumieniowo tylko dla GET żądań. Aby uzyskać więcej informacji, zobacz Pozwalanie na strumieniowe ładowanie odpowiedzi POST (dotnet/aspnetcore #50994).

Uwaga

Linki dokumentacyjne do źródła referencyjnego .NET zwykle ładują domyślną gałąź repozytorium, która odzwierciedla obecne prace rozwojowe nad nadchodzącą wersją .NET. Aby wybrać tag dla określonej wersji, użyj listy rozwijanej Przełącz gałęzie lub tagi. Aby uzyskać więcej informacji, zobacz Jak wybrać tag wersji kodu źródłowego platformy ASP.NET Core (dotnet/AspNetCore.Docs #26205).

† Aby uzyskać więcej informacji na temat powiązania właściwości, zobacz Blazor.

W następnym przykładzie poprzedni składnik zostanie zmodyfikowany w celu utworzenia formularza w składniku Starship2 :

• OnSubmit Element jest zastępowany elementem , który przetwarza przypisaną procedurę OnValidSubmitobsługi zdarzeń, jeśli formularz jest prawidłowy podczas przesyłania przez użytkownika.
• Składnik ValidationSummary jest dodawany do wyświetlania komunikatów weryfikacji, gdy formularz jest nieprawidłowy podczas przesyłania formularza.
• Walidator adnotacji danych (DataAnnotationsValidator komponent†) zapewnia obsługę walidacji przy użyciu adnotacji danych:
  • <input> Jeśli pole formularza pozostanie puste po wybraniu przycisku Submit, w podsumowaniu weryfikacji (ValidationSummary składnik‡) ("The Id field is required.") pojawia się błąd i Submit niejest wywoływany.
  • Jeśli po wybraniu przycisku <input> pole formularza Submit zawiera więcej niż dziesięć znaków, w podsumowaniu weryfikacji pojawi się błąd ("Id is too long."). Submitnie jest wywoływana.
  • <input> Jeśli pole formularza zawiera prawidłową wartość po wybraniu Submit przycisku, Submit jest wywoływana.

†Składnik DataAnnotationsValidator jest omówiony w sekcji Składnik modułu sprawdzania poprawności. }Składnik ValidationSummary jest omówiony w sekcji Składniki podsumowania i komunikatu weryfikacji.

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]
    private 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; }
    }
}

Obsługa przesyłania formularza

Program EditForm udostępnia następujące wywołania zwrotne do obsługi przesyłania formularza:

• Użyj OnValidSubmit polecenia , aby przypisać procedurę obsługi zdarzeń, aby uruchomić formularz z prawidłowymi polami.
• Użyj OnInvalidSubmit polecenia , aby przypisać procedurę obsługi zdarzeń do uruchomienia po przesłaniu formularza z nieprawidłowymi polami.
• Użyj polecenia OnSubmit , aby przypisać procedurę obsługi zdarzeń do uruchomienia niezależnie od stanu weryfikacji pól formularza. Formularz jest weryfikowany przez wywołanie metody obsługi zdarzeń EditContext.Validate. Jeśli Validate zwraca wartość true, formularz jest prawidłowy.

Czyszczenie formularza lub pola

Zresetuj formularz, przywracając jego model do stanu domyślnego, co można zrobić wewnątrz lub poza znacznikiem EditForm.

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

...

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

Alternatywnie użyj wyrażenia jawnego Razor :

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

Zresetuj pole, usuwając jego wartość modelu z powrotem do stanu domyślnego:

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

...

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

Alternatywnie użyj wyrażenia jawnego Razor :

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

Nie ma potrzeby wywoływania StateHasChanged w poprzednich przykładach, ponieważ StateHasChanged program jest automatycznie wywoływany przez platformę Blazor w celu rerender składnika po wywołaniu programu obsługi zdarzeń. Jeśli program obsługi zdarzeń nie jest używany do wywoływania metod, które czyszczą formularz lub pole, kod dewelopera powinien wywoływać StateHasChanged w celu ponownego wyrenderowania składnika.

Obsługa zabezpieczeń przed fałszerstwami

Usługi antyfałszerskie są automatycznie dodawane do aplikacji Blazor, gdy w pliku wywołana zostanie funkcja AddRazorComponentsProgram.

Aplikacja używa oprogramowania pośredniczącego Antiforgery przez wywołanie UseAntiforgery w potoku przetwarzania żądań w pliku Program. UseAntiforgery jest wywoływana po wywołaniu UseRouting. Jeśli istnieją połączenia do UseRouting i UseEndpoints, wywołanie UseAntiforgery musi znaleźć się pomiędzy nimi. Wywołanie UseAntiforgery musi zostać umieszczone po wywołaniach UseAuthentication i UseAuthorization.

Składnik AntiforgeryToken renderuje token antyfałszerstwowy jako ukryte pole, a atrybut [RequireAntiforgeryToken] umożliwia ochronę przed fałszerstwem. Jeśli weryfikacja antyfałszerstwa się nie powiedzie, zgłoszona zostanie 400 - Bad Request odpowiedź i formularz nie zostanie przetworzony.

W przypadku formularzy opartych na EditForm, składnik AntiforgeryToken i atrybut [RequireAntiforgeryToken] są automatycznie dodawane w celu zapewnienia ochrony przed fałszerstwem.

W przypadku formularzy opartych na elemencie HTML <form> ręcznie dodaj AntiforgeryToken składnik do formularza:

<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;
}

Ostrzeżenie

W przypadku formularzy opartych na elememencie EditForm HTML <form> można wyłączyć ochronę przed fałszerzją, przekazując required: false do atrybutu [RequireAntiforgeryToken] . Poniższy przykład wyłącza funkcję ochrony przed fałszerzją i nie jest zalecany w przypadku aplikacji publicznych:

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

Aby uzyskać więcej informacji, zobacz uwierzytelnianie i autoryzacja w ASP.NET CoreBlazor.

Łagodzenie ataków nadmiernego przesyłania danych

Statycznie renderowane formularze po stronie serwera, takie jak te, które są zwykle używane w składnikach tworzących i edytujących rekordy w bazie danych z modelem formularzy, mogą być narażone na atak nadmierny , znany również jako atak masowego przypisania . Atak overposting występuje, gdy złośliwy użytkownik wysyła formularz POST HTML na serwer, który przetwarza dane właściwości formularza, które nie są częścią renderowanego formularza, i do których deweloper nie chce umożliwić użytkownikom dostępu lub modyfikacji. Termin "overposting" oznacza dosłownie, że złośliwy użytkownik zastosował nadmierne wysyłanie POST z formularzem.

Overposting nie jest problemem, gdy model nie zawiera ograniczonych właściwości operacji tworzenia i aktualizowania. Jednak ważne jest, aby pamiętać o problemie nadmiarowego przesyłania podczas pracy ze statycznymi formularzami opartymi na Blazor SSR, które utrzymujesz.

Aby zminimalizować nadmierne przesyłanie danych, zalecamy stosowanie oddzielnego modelu widoku/obiektu transferu danych (DTO) dla formularza i bazy danych, przy operacjach wstawiania i aktualizacji. Po przesłaniu formularza tylko właściwości modelu widoku/DTO są używane przez składnik i kod C# do modyfikowania bazy danych. Wszelkie dodatkowe dane zawarte przez złośliwego użytkownika są odrzucane, więc złośliwy użytkownik nie może przeprowadzić ataku overpostingu.

Ulepszona obsługa formularzy

Ulepsz nawigację dla żądań POST formularza za pomocą parametru Enhance dla formularzy lub atrybutu EditForm dla formularzy HTML (data-enhance):

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

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

❌ Nieobsługiwane: nie można ustawić rozszerzonej nawigacji na elemencie przodkowym formularza, aby włączyć rozszerzoną obsługę formularzy.

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

Rozszerzone wpisy formularza działają tylko z końcowymi punktami Blazor. Opublikowanie rozszerzonego formularza do nie-Blazor punktu końcowego powoduje wystąpienie błędu.

Aby wyłączyć rozszerzoną obsługę formularzy:

• W przypadku elementu EditFormusuń Enhance parametr z elementu formularza (lub ustaw go na wartość false: Enhance="false").
• W przypadku kodu HTML <form>usuń data-enhance atrybut z elementu formularza (lub ustaw go na wartość false: data-enhance="false").

BlazorUlepszona nawigacja i obsługa formularzy mogą cofnąć zmiany dynamiczne w modelu DOM, jeśli zaktualizowana zawartość nie jest częścią renderowania serwera. Aby zachować zawartość elementu, użyj atrybutu data-permanent .

W poniższym przykładzie zawartość <div> elementu jest aktualizowana dynamicznie przez skrypt podczas ładowania strony:

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

Aby wyłączyć rozszerzoną nawigację i obsługę formularzy globalnie, zobacz uruchamianie ASP.NET CoreBlazor.

Aby uzyskać wskazówki dotyczące używania enhancedload zdarzenia do nasłuchiwania rozszerzonych aktualizacji stron, zobacz ASP.NET Core Blazor routing i nawigacja.

Przykłady

Przykłady nie wykorzystują ulepszonej obsługi formularzy dla żądań POST, ale wszystkie można zaktualizować, aby wdrożyć te ulepszone funkcje, postępując zgodnie ze wskazówkami w sekcji Ulepszona obsługa formularzy.

Aby zademonstrować sposób pracy formularzy z walidacją danych przy użyciu adnotacji, przykładowe komponenty korzystają z System.ComponentModel.DataAnnotations interfejsu API. Jeśli chcesz uniknąć dodatkowego wiersza kodu w składnikach korzystających z adnotacji danych, udostępnij przestrzeń nazw w składnikach aplikacji przy użyciu pliku importu (_Imports.razor):

@using System.ComponentModel.DataAnnotations

Przykładowe formularze odwołują się do aspektów wszechświata Star Trek. Star Trek jest prawem autorskim ©1966-2023 CBS Studios i Paramount.

Walidacja po stronie klienta wymaga obwodu

W Blazor Web App, weryfikacja po stronie klienta wymaga aktywnego obwodu BlazorSignalR. Walidacja po stronie klienta nie jest dostępna dla formularzy w składnikach, które przyjęły statyczne renderowanie po stronie serwera (statyczne SSR). Formularze, które przyjmują statyczne SSR, są weryfikowane na serwerze po przesłaniu formularza.

Nieobsługiwane funkcje walidacji

Wszystkie wbudowane walidatory adnotacji danych są obsługiwane , z wyjątkiem atrybutu walidacji Blazor.

Walidacja jQuery nie jest obsługiwana w Razor składnikach. Zalecamy dowolne z następujących podejść:

• Postępuj zgodnie ze wskazówkami dotyczącymi walidacji formularzy Blazor ASP.NET Core dla:
  • Walidacja po stronie serwera w Blazor Web App programie, który przyjmuje tryb renderowania interakcyjnego.
  • Walidacja po stronie klienta w autonomicznej Blazor aplikacji WebAssembly.
• Użyj natywnych atrybutów weryfikacji HTML (zobacz Walidacja formularza po stronie klienta).
• Adopt a third-party validation JavaScript library (Wdrażanie biblioteki JavaScript walidacji innej firmy).

W przypadku statycznie renderowanych formularzy na serwerze nowy mechanizm weryfikacji po stronie klienta jest brany pod uwagę pod kątem platformy .NET 10 pod koniec 2025 r. Aby uzyskać więcej informacji, zobacz Create server rendered forms with client validation using without a circuit ( #51040)( Tworzenie formularzy renderowanych przez serwer z walidacją klienta przy użyciu Blazor bez obwodu (dotnet/aspnetcore #51040).

Dodatkowe zasoby

• przekazywanie plików ASP.NET Core Blazor
• Blazor (dotnet/blazor-samples) (Blazor)
• dotnet/aspnetcore