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 součásti.
• Integrované vstupní komponenty.

Poznámka:

Nepodporované funkce ověřování ASP.NET Core najdete v části Nepodporované funkce ověřování.

Obor Microsoft.AspNetCore.Components.Forms názvů 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ý ze Blazor šablony projektu obsahuje obor názvů v souboru aplikace _Imports.razor , který zpřístupňuje 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 se vytvoří v bloku komponenty @code a nachází se ve veřejné vlastnosti (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 Model.Id vytvoří vazbu vlastnosti modelu na InputText vlastnost komponenty Value .
• 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 @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, aby se použila odpověď na stávající model DOM a zachovala 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 Blazor Základní směrování a navigace.

Vykreslování streamování je podporováno pro prosté formuláře HTML.

Poznámka:

Odkazy na dokumentaci k referenčnímu zdroji .NET 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řepnutí větví nebo značek. Další informace najdete v tématu Jak vybrat značku verze zdrojového kódu ASP.NET Core (dotnet/AspNetCore.Docs #26205).

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

Pokud chcete odeslat formulář na základě událostí DOM jiného prvku, například oninput pomocí JavaScriptu odešlete formulář (submit (dokumentace MDN)).onblur

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ář má název s atributem @formname direktivy, který jednoznačně identifikuje formulář pro architekturu Blazor .
• Model se vytvoří v bloku komponenty @code a nachází se ve veřejné vlastnosti (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í komponenta pro úpravu řetězcových hodnot. Atribut @bind-Value direktivy Model.Id vytvoří vazbu vlastnosti modelu na InputText vlastnost komponenty Value .
• 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 @formname atribut direktivy 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 Blazor Základní směrování a navigace.

Vykreslování streamování je podporováno pro EditForm.

Poznámka:

Odkazy na dokumentaci k referenčnímu zdroji .NET 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řepnutí větví nebo značek. Další informace najdete v tématu Jak vybrat značku verze zdrojového kódu ASP.NET Core (dotnet/AspNetCore.Docs #26205).

† Další informace o vazbě vlastností najdete v tématu ASP.NET Základní Blazor datová vazba.

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

• OnSubmit je nahrazena obslužnou rutinou OnValidSubmitudálosti, která zpracovává přiřazenou obslužnou rutinu 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:
  • <input> Pokud je pole formuláře při výběru tlačítka prázdnéSubmit, zobrazí se v souhrnu ověření (ValidationSummarykomponenta")) ("The Id field is required.") chyba a Submit není 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."). Submitnení volána.
  • <input> Pokud pole formuláře obsahuje platnou Submit hodnotu při výběru tlačítka, Submit je volána.

†Položka DataAnnotationsValidator se zabývá částí 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

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

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

Vymazání formuláře nebo pole

Resetováním formuláře vymažete jeho výchozí stav, který lze provést uvnitř nebo mimo EditFormznačku modelu:

<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 zpět do výchozí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 rozhraní automaticky volá Blazor komponentu znovu 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 antiforgery

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

Aplikace používá Middleware Antiforgery voláním UseAntiforgery v kanálu zpracování požadavků v Program souboru. UseAntiforgery je volána po volání UseRouting. Pokud existují volání UseRouting a UseEndpointsvolání musí UseAntiforgery jít mezi nimi. Hovor UseAntiforgery musí být umístěn po volání a UseAuthentication UseAuthorization.

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

U formulářů založených na EditFormkomponentě a [RequireAntiforgeryToken] atributu AntiforgeryToken se automaticky přidají 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;
}

Upozorňující

U formulářů založených na elementu EditForm HTML <form> lze antiforgery ochranu zakázat předáním required: false atributu [RequireAntiforgeryToken] . Následující příklad zakáže antiforgery a nedoporučuje se pro veřejné aplikace:

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

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

Zmírnění nadměrného příspěvku útoků

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, můžou být zranitelné vůči útoku, který se označuje také jako útok hromadného přiřazení . Útok na nadměrné odeslání nastane, když uživatel se zlými úmysly vydá formulář HTML POST na server, který zpracovává data pro vlastnosti, které nejsou součástí vykresleného formuláře a že vývojář nechce uživatelům povolit úpravy. Pojem "overposting" doslova znamená, že uživatel se zlými úmysly přetáčí s formulářem.

Overposting není problém, pokud model neobsahuje omezené vlastnosti pro operace vytváření a aktualizace. Při práci se statickými formuláři založenými na Blazor SSR, které spravujete, je ale důležité mít na paměti.

Pokud chcete zmírnit nadměrné umístění, doporučujeme pro formulář a databázi použít samostatný model zobrazení nebo objekt pro přenos dat (DTO) s operacemi 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á uživatelem se zlými úmysly se zahodí, takže škodlivému uživateli se zabrání v provedení útoku proti útoku.

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é příspěvky formulářů fungují jenom s Blazor koncovými body. Publikování rozšířeného formuláře do jinéhoBlazor koncového bodu způsobí chybu.

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

• Pro parametr odeberte EditFormEnhance z elementu formuláře parametr (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 předává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 zakázat rozšířenou navigaci a zpracování formulářů globálně, přečtěte si informace o spuštění ASP.NET CoreBlazor.

Pokyny k používání enhancedload události k naslouchání rozšířeným aktualizacím stránek najdete v tématu ASP.NET Směrování a navigace v jádruBlazor.

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 autorská práva ©1966-2023 CBS Studios a Paramount.

Ověření na straně klienta vyžaduje okruh.

Ověření Blazor Web Appna straně klienta vyžaduje aktivní BlazorSignalR okruh. 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é přijímají statické služby SSR, se po odeslání formuláře 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 se v komponentách nepodporuje Razor . Doporučujeme některý z následujících přístupů:

• Postupujte podle pokynů v ASP.NET Blazor ověřování základních formulářů pro jednu z těchto metod:
  • Ověřování na straně serveru v Blazor Web App režimu interaktivního vykreslování.
  • Ověřování na straně klienta v samostatné Blazor aplikaci webového sestavení
• Použití nativních ověřovacích atributů HTML (viz ověření formuláře na straně klienta (dokumentace k MDN)).
• Přijměte javascriptovou knihovnu pro ověřování třetí strany.

U staticky vykreslených formulářů na serveru je pro .NET 10 na konci roku 2025 zvažován nový mechanismus ověřování na straně klienta. Další informace naleznete v tématu Vytvoření vykreslíných formulářů serveru s ověřováním klienta pomocí bez Blazor okruhu (dotnet/aspnetcore #51040).

Další materiály

• nahrávání souborů ASP.NET Core Blazor
• Blazorukázky úložiště GitHub () (dotnet/blazor-samplespostup stažení)
• ASP.NET základních testovacích prostředků GitHubudotnet/aspnetcore