přehled formulářů ASP.NET Core Blazor

Tento článek vysvětluje, jak používat formuláře v Blazor.

Vstupní komponenty a formuláře

Architektura Blazor podporuje formuláře a poskytuje integrované vstupní komponenty:

• Svázaný s objektem nebo modelem, který může používat datové poznámky.
  • Formuláře HTML s elementem <form> .
  • EditForm komponenty.
• Integrované vstupní komponenty.

Poznámka:

Nepodporované funkce ověřování ASP.NET Core jsou popsané v části Podporované ověřovací funkce.

Obor názvů Microsoft.AspNetCore.Components.Forms poskytuje:

• Třídy pro správu prvků formuláře, stavu a ověřování
• Přístup k integrovaným Input* komponentám

Projekt vytvořený z šablony projektu Blazor obsahuje obor názvů v souboru aplikace _Imports.razor, což zpřístupňuje tento obor názvů komponentám aplikace Razor.

Podporují se standardní formuláře HTML. Vytvořte formulář pomocí normální značky HTML <form> a zadejte obslužnou rutinu @onsubmit pro zpracování odeslané žádosti o formulář.

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

V předchozí StarshipPlainForm komponentě:

• Formulář se vykreslí tam, kde se <form> prvek zobrazí. Formulář má název s atributem @formname direktivy, který jednoznačně identifikuje formulář pro architekturu Blazor .
• Model je vytvořen v bloku komponenty @code a je uložen ve vlastnosti public (Model). Atribut [SupplyParameterFromForm] označuje, že hodnota přidružené vlastnosti by měla být zadána z dat formuláře. Data v požadavku, který odpovídá názvu vlastnosti, jsou svázaná s vlastností.
• Komponenta InputText je vstupní komponenta pro úpravu řetězcových hodnot. Atribut @bind-Value direktivy váže vlastnost modelu na vlastnost komponenty Model.Id.
• Metoda Submit je registrována jako obslužná rutina pro zpětné volání @onsubmit. Obslužná rutina je volána při odeslání formuláře uživatelem.

Důležité

Vždy použijte @formname atribut direktivy s jedinečným názvem formuláře.

Blazor vylepšuje navigaci na stránce a zpracování formulářů tím, že zachytí požadavek a aplikuje odpověď na stávající DOM, přičemž zachovává co nejvíce vykresleného formuláře. Toto vylepšení se vyhne nutnosti plně načíst stránku a poskytuje mnohem plynulejší uživatelské prostředí, podobně jako jednostránková aplikace (SPA), i když se komponenta vykresluje na serveru. Další informace najdete v tématu ASP.NET Core Blazor navigace.

Streamované vykreslování je podporováno pro prosté formuláře HTML. Všimněte si, že při použití POST formuláře se streamují pouze aktualizace DOM uvnitř obslužných rutin tohoto formuláře (například @onsubmit). Aktualizace uvnitř OnInitializedAsync jsou streamovány pouze pro požadavky GET. Další informace najdete v tématu Povolit streamování fáze načítání odpovědí POST (dotnet/aspnetcore #50994).

Poznámka:

Odkazy na dokumentaci ke .NET referenčnímu zdroji obvykle načítají výchozí větev úložiště, která představuje aktuální vývoj pro příští verzi .NET. Pokud chcete vybrat značku pro konkrétní verzi, použijte rozevírací seznam pro přepínání větví nebo značek. Další informace najdete v tématu Jak vybrat značku verzí zdrojového kódu pro ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Předchozí příklad obsahuje podporu proti padělání pomocí komponenty AntiforgeryToken zahrnuté ve formuláři. Podpora antiforgery je podrobněji vysvětlena v části Podpora antiforgery tohoto článku.

Chcete-li odeslat formulář na základě událostí DOM jiného prvku, například oninput nebo onblur, použijte JavaScript k odeslání formuláře (submit).

Místo použití prostých formulářů v Blazor aplikacích se formulář obvykle definuje s Blazorintegrovanou podporou formulářů pomocí komponenty architektury EditForm . Následující Razor komponenta demonstruje typické prvky, komponenty a Razor kód k vykreslení webového EditForm formuláře pomocí komponenty.

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

V předchozí Starship1 komponentě:

• Komponenta EditForm se vykreslí tam, kde se <EditForm> prvek zobrazí. Formulář je pojmenován pomocí vlastnosti FormName, která jednoznačně identifikuje formulář pro rozhraní Blazor.
• Model je vytvořen v bloku komponenty @code a je uložen ve vlastnosti public (Model). Vlastnost je přiřazena k parametru EditForm.Model . Atribut [SupplyParameterFromForm] označuje, že hodnota přidružené vlastnosti by měla být zadána z dat formuláře. Data v požadavku, který odpovídá názvu vlastnosti, jsou svázaná s vlastností.
• Komponenta InputText je vstupní komponentapro úpravu řetězcových hodnot. Atribut @bind-Value direktivy váže vlastnost modelu na vlastnost komponenty Model.Id.
• Metoda Submit je registrována jako obslužná rutina OnSubmit pro zpětné volání. Obslužná rutina je volána při odeslání formuláře uživatelem.

Důležité

Vždy použijte vlastnost FormName s jedinečným názvem formuláře.

Blazor vylepšuje navigaci na stránce a zpracování formulářů pro EditForm komponenty. Další informace najdete v tématu ASP.NET Core Blazor navigace.

Vykreslování streamování je podporováno pro EditForm. Všimněte si, že při použití POST formuláře se streamují pouze aktualizace DOM uvnitř obslužných rutin tohoto formuláře (například OnValidSubmit). Aktualizace uvnitř OnInitializedAsync jsou streamovány pouze pro požadavky GET. Další informace najdete v tématu Povolit streamování fáze načítání odpovědí POST (dotnet/aspnetcore #50994).

Poznámka:

Odkazy na dokumentaci ke .NET referenčnímu zdroji obvykle načítají výchozí větev úložiště, která představuje aktuální vývoj pro příští verzi .NET. Pokud chcete vybrat značku pro konkrétní verzi, použijte rozevírací seznam pro přepínání větví nebo značek. Další informace najdete v tématu Jak vybrat značku verzí zdrojového kódu pro ASP.NET Core (dotnet/AspNetCore.Docs #26205).

† Další informace o vazbě vlastností najdete v tématu ASP.NET Core Blazor datové vazby.

V dalším příkladu je předchozí komponenta upravena tak, aby vytvořila formulář v komponentě Starship2 :

• OnSubmit je nahrazen OnValidSubmit, který zpracovává přiřazenou obsluhu události, pokud je formulář platný při odeslání uživatelem.
• Komponenta ValidationSummary se přidá k zobrazení ověřovacích zpráv, pokud je formulář při odeslání formuláře neplatný.
• Validátor datových poznámek (DataAnnotationsValidator součást†) připojuje podporu ověřování pomocí datových poznámek:
  • Pokud je pole formuláře <input> ponecháno prázdné při výběru tlačítka Submit, zobrazí se v souhrnu ověření (ValidationSummary komponenta) („The Id field is required.“) chyba a Submitnení volána.
  • <input> Pokud pole formuláře obsahuje při výběru tlačítka více než deset znakůSubmit, zobrazí se v souhrnu ověření chyba ("Id is too long."). Submit není volána.
  • Pokud pole formuláře obsahuje platnou hodnotu při výběru tlačítka <input>, je volána funkce Submit.

†Komponenta DataAnnotationsValidator je pokryta v části komponenty Validator. ValidationSummary Součást je popsána v části Souhrn ověření a Ověřovací zpráva.

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

Zpracování odeslání formuláře

EditForm poskytuje následující zpětná volání pro zpracování odeslání formuláře:

• Použijte OnValidSubmit k přiřazení obslužné rutiny události, která se spustí při odeslání formuláře s platnými poli.
• Použijte OnInvalidSubmit k přiřazení obslužné rutiny události, která se spustí při odeslání formuláře s neplatnými poli.
• OnSubmit slouží k přiřazení obslužné rutiny události k spuštění bez ohledu na stav ověření polí formuláře. Formulář je ověřen voláním EditContext.Validate v obslužné metodě události. Pokud se Validate vrátí jako true, formulář je platný.

Vymazání formuláře nebo pole

Resetování formuláře vrátí jeho model do výchozího stavu a lze to provést uvnitř nebo vně značek EditForm.

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

...

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

Případně použijte explicitní Razor výraz:

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

Resetováním pole vymažete jeho hodnotu modelu do původního stavu.

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

...

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

Případně použijte explicitní Razor výraz:

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

V předchozích příkladech není nutné volat StateHasChanged, protože StateHasChanged je automaticky volán frameworkem Blazor k opětovnému znovuzobrazení komponenty po vyvolání obslužné rutiny události. Pokud se obslužná rutina události nepoužívá k vyvolání metod, které vymažou formulář nebo pole, měl by kód vývojáře volat StateHasChanged , aby komponentu znovu vymazal.

Podpora antifalšovací

Služby antiforgery se automaticky přidají do Blazor aplikací, když je AddRazorComponents volána v souboru Program.

Aplikace používá middleware pro ochranu proti padělání požadavků pomocí volání UseAntiforgery v kanálu pro zpracování požadavků v souboru Program. UseAntiforgery je volána po volání UseRouting. Pokud existují volání UseRouting a UseEndpoints, volání na UseAntiforgery musí jít mezi nimi. Hovor UseAntiforgery musí být proveden po volání na UseAuthentication a UseAuthorization.

Komponenta AntiforgeryToken vykresluje antiforgery token jako skryté pole a [RequireAntiforgeryToken] atribut umožňuje ochranu proti padělání. Pokud se kontrola antiforgery nezdaří, vyvolá se odpověď 400 - Bad Request a formulář se nezpracuje.

U formulářů založených na EditForm se automaticky přidá komponenta AntiforgeryToken a atribut [RequireAntiforgeryToken] za účelem zajištění ochrany proti padělání.

Pro formuláře založené na elementu HTML <form> ručně přidejte komponentu AntiforgeryToken do formuláře:

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

Varování

Pro formuláře založené na HTML elementu EditForm nebo <form> lze antiforgery ochranu zakázat předáním hodnoty required: false k atributu [RequireAntiforgeryToken]. Následující příklad zakáže ochranu antiforgery a není doporučeno pro veřejné aplikace:

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

Další informace najdete v tématu ASP.NET Core Blazor ověřování a autorizace.

Zmírnění útoků nadměrným odesíláním dat

Staticky vykreslené formuláře na straně serveru, například formuláře, které se obvykle používají v komponentách, které vytvářejí a upravují záznamy v databázi s modelem formuláře, mohou být zranitelné vůči útoku zvanému overposting, také známému jako útok pomocí hromadného přiřazení. Útok na nadměrné odeslání nastane, když uživatel se zlými úmysly odešle formulář HTML POST na server, který zpracovává data pro vlastnosti, jež nejsou součástí vykresleného formuláře a které vývojář nechce uživatelům povolit upravovat. Pojem "overposting" doslova znamená, že uživatel se zlými úmysly nadměrně posílal POST požadavky s formulářem.

Overposting není problém, pokud model neobsahuje omezené vlastnosti pro operace vytváření a aktualizace. Je však důležité mít na paměti nadměrné zasílání při práci se statickými formuláři založenými na SSR, které spravujete.

Aby se zabránilo nadměrnému odesílání, doporučujeme pro formulář a databázi použít samostatný model zobrazení a objekt pro přenos dat (DTO) při operacích vytvoření (vložení) a aktualizace. Při odeslání formuláře se k úpravě databáze používají pouze vlastnosti modelu zobrazení nebo DTO komponenty a kódu jazyka C#. Veškerá další data zahrnutá škodlivým uživatelem se zahodí, takže škodlivému uživateli se zabrání v provedení útoku vícenásobného odeslání.

Vylepšené zpracování formulářů

Vylepšení navigace pro požadavky POST formuláře s parametrem Enhance formulářů EditForm nebo atributem data-enhance pro formuláře HTML (<form>):

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

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

❌ Nepodporováno: U nadřazeného prvku formuláře nelze nastavit rozšířenou navigaci, která umožňuje rozšířené zpracování formulářů.

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

Vylepšené formulářové příspěvky fungují pouze s Blazor koncovými body. Publikování vylepšeného formuláře na nesprávnýBlazor koncový bod způsobí chybu.

Zakázání rozšířeného zpracování formulářů:

• Pro odebrání EditForm, odstraňte parametr Enhance z elementu formuláře (nebo ho nastavte na false: Enhance="false").
• Pro HTML <form>odeberte data-enhance atribut z elementu formuláře (nebo ho nastavte na false: data-enhance="false").

BlazorVylepšená navigace a zpracování formulářů můžou vrátit dynamické změny modelu DOM, pokud aktualizovaný obsah není součástí vykreslování serveru. Chcete-li zachovat obsah elementu, použijte data-permanent atribut.

V následujícím příkladu se obsah elementu <div> dynamicky aktualizuje skriptem při načtení stránky:

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

Pokud chcete rozšířené procházení a zpracování formulářů zakázat globálně, přečtěte si článek ASP.NET Core Blazor spuštění.

Pokyny k používání události enhancedload k naslouchání aktualizacím rozšířených stránek najdete v tématu ASP.NET Core Blazor navigace.

Příklady

Příklady nepodporují rozšířené zpracování formulářů pro žádosti POST, ale všechny příklady je možné aktualizovat, aby přijaly vylepšené funkce podle pokynů v části Rozšířené zpracování formulářů.

Abychom si ukázali, jak formuláře fungují s ověřováním datových poznámek , využívají System.ComponentModel.DataAnnotations ukázkové komponenty rozhraní API. Pokud se chcete vyhnout nadbytečnému řádku kódu v komponentách, které používají datové poznámky, zpřístupňte obor názvů v rámci komponent aplikace souborem importu (_Imports.razor):

@using System.ComponentModel.DataAnnotations

Příklady formulářů odkazují na aspekty vesmíru Star Trek . Star Trek je chráněný autorskými právy ©1966-2023 společností CBS Studios a Paramount.

Ověření na straně klienta vyžaduje specifický proces.

Blazor Web Appověření na klientské straně vyžaduje aktivní BlazorSignalR obvod. Ověřování na straně klienta není k dispozici pro formuláře v součástech, které přijaly statické vykreslování na straně serveru (statické SSR). Formuláře, které používají statický SSR, se po odeslání ověřují na serveru.

Nepodporované funkce ověřování

Všechny předdefinované validátory datových poznámek jsou podporovány Blazor s výjimkou ověřovacího atributu[Remote].

Ověřování jQuery není podporováno v komponentách Razor. Doporučujeme některý z následujících přístupů:

• Postupujte podle pokynů v ASP.NET Core Blazor ověřování formulářů pro:
  • Ověřování na straně serveru v interaktivním režimu vykreslování v Blazor Web App.
  • Ověřování na straně klienta v samostatné Blazor WebAssembly aplikaci
• Použití nativních ověřovacích atributů HTML (viz ověření formuláře na straně klienta).
• Přijměte javascriptovou knihovnu pro ověřování třetí strany.

Další materiály

• ASP.NET Core Blazor nahrávání souborů
• Blazor ukázky GitHub úložiště (dotnet/blazor-samples) (jak stáhnout)
• Úložiště ASP.NET Core GitHub (dotnet/aspnetcore) pro sestavení testovacích prostředků