Omówienie formularzy 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>
  • Składniki EditForm
• Wbudowane składniki wejściowe

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 projektu domyślnie zawiera przestrzeń nazw w pliku aplikacji, która udostępnia przestrzeń nazw składnikom aplikacji _Imports.razorRazor .

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

W poprzednim StarshipPlainForm składniku:

• Formularz jest renderowany, gdzie <form> pojawia się element. 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 jest zarejestrowana Submit jako procedura obsługi wywołania zwrotnego @onsubmit . Procedura obsługi jest wywoływana po przesłaniu formularza przez użytkownika.

Ważne

Zawsze używaj atrybutu @formname dyrektywy z unikatową nazwą formularza.

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, zobacz ASP.NET Core Blazor routing i nawigacja.

Renderowanie strumieniowe jest obsługiwane w przypadku zwykłych formularzy HTML.

Uwaga

Linki dokumentacji do źródła referencyjnego platformy .NET zwykle ładują domyślną gałąź repozytorium, która odzwierciedla bieżące programowanie dla następnej wersji platformy .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 przed fałszerzami, dołączając AntiforgeryToken składnik 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 (submitdokumentacja MDN).

Zamiast używać zwykłych formularzy w Blazor aplikacjach, formularz jest zwykle definiowany z wbudowaną obsługą Blazorformularzy przy użyciu składnika platformy EditForm . Poniższy Razor składnik przedstawia typowe elementy, składniki i Razor kod w celu renderowania kształtów internetowych przy użyciu EditForm składnika.

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

W poprzednim Starship1 składniku:

• Składnik EditForm jest renderowany, gdzie <EditForm> pojawia się element. 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). 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 jest zarejestrowana Submit jako procedura obsługi wywołania zwrotnego OnSubmit . Procedura obsługi jest wywoływana po przesłaniu formularza przez użytkownika.

Ważne

Zawsze używaj atrybutu @formname dyrektywy z unikatową nazwą formularza.

Blazor Usprawnia nawigację po stronie i obsługę formularzy dla EditForm składników. Aby uzyskać więcej informacji, zobacz ASP.NET Core Blazor routing i nawigacja.

Renderowanie przesyłania strumieniowego jest obsługiwane w przypadku programu EditForm.

Uwaga

Linki dokumentacji do źródła referencyjnego platformy .NET zwykle ładują domyślną gałąź repozytorium, która odzwierciedla bieżące programowanie dla następnej wersji platformy .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 powiązanie danych ASP.NET CoreBlazor.

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.
• Moduł sprawdzania poprawności adnotacji danych (DataAnnotationsValidator składnik†) dołącza obsługę walidacji przy użyciu adnotacji danych:
  • <input> Jeśli pole formularza pozostanie puste po wybraniu Submit przycisku, w podsumowaniu weryfikacji (ValidationSummaryskładnik}) ("The Id field is required.") pojawia się błąd i Submit nie jest wywoływany.
  • <input> Jeśli pole formularza zawiera więcej niż dziesięć znaków po wybraniu Submit przycisku, w podsumowaniu weryfikacji ("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]
    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; }
    }
}

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 EditContext.Validate metody obsługi zdarzeń. Jeśli Validate zwraca truewartość , formularz jest prawidłowy.

Czyszczenie formularza lub pola

Zresetuj formularz, usuwając jego model z powrotem stan domyślny, który można wykonać 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 czyszczają formularz lub pole, kod dewelopera powinien wywołać StateHasChanged element rerender składnika.

Obsługa ochrony przed fałszerzami

Usługi ochrony przed fałszerzami są automatycznie dodawane do Blazor aplikacji, gdy AddRazorComponents jest wywoływana Program w pliku.

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

Składnik AntiforgeryToken renderuje token antyforgery jako ukryte pole, a [RequireAntiforgeryToken] atrybut umożliwia ochronę przed fałszerzją. Jeśli sprawdzanie antyforgery nie powiedzie się, zostanie 400 - Bad Request zgłoszony odpowiedź i formularz nie zostanie przetworzony.

W przypadku formularzy opartych na EditFormskładniku AntiforgeryToken i [RequireAntiforgeryToken] atrybucie są automatycznie dodawane w celu zapewnienia ochrony przed fałszerzją domyślnie.

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 ASP.NET Core authentication and authorization (Uwierzytelnianie i autoryzacja na platformie ASP.NET CoreBlazor).

Ulepszona obsługa formularzy

Ulepszanie nawigacji dla żądań POST formularza za pomocą parametru Enhance formularzy lub atrybutu data-enhance formularzy EditForm HTML (<form>):

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

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

❌Nieobsługiwane: nie można ustawić rozszerzonej nawigacji na elemektorze przodka formularza w celu włączenia rozszerzonej obsługi formularzy.

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

Rozszerzone wpisy formularza działają tylko z punktami Blazor końcowymi. Opublikowanie rozszerzonego formularza wBlazor punkcie końcowym 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 przekazywanie formularzy mogą cofnąć dynamiczne zmiany 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 przyjmują rozszerzonej obsługi formularzy dla żądań POST formularza, ale wszystkie przykłady można zaktualizować w celu wdrożenia rozszerzonych funkcji, postępując zgodnie ze wskazówkami w sekcji Rozszerzona obsługa formularzy .

Aby zademonstrować sposób pracy formularzy z walidacją adnotacji danych, przykładowe składniki 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łady formularzy odwołują się do aspektów wszechświata Star Trek . Star Trek jest prawem autorskim ©1966-2023 CBS Studios i Paramount.

Dodatkowe zasoby

• przekazywanie plików ASP.NET Core Blazor
• Blazorprzykładowe repozytorium GitHub () (dotnet/blazor-samplesjak pobrać)
• ASP.NET Core repozytorium GitHub (dotnet/aspnetcore) zasobów testowych formularzy