ASP.NET Core Blazor-űrlapok áttekintése

Ez a cikk bemutatja, hogyan használhatók az űrlapok a Blazor-ban.

Bemeneti összetevők és űrlapok

A Blazor keretrendszer támogatja az űrlapokat, és beépített bemeneti összetevőket biztosít:

• Olyan objektumhoz vagy modellhez van kötve, amely adatjegyzetekethasználhat.
  • HTML-űrlapok a <form> elemmel.
  • EditForm összetevők.
• beépített bemeneti komponensek.

Jegyzet

A nem támogatott ASP.NET Alapvető érvényesítési funkciók a Nem támogatott érvényesítési funkciók szakaszban találhatók.

A Microsoft.AspNetCore.Components.Forms névtér a következőt biztosítja:

• Osztály az űrlapelemek, az állapot és az ellenőrzés kezeléséhez.
• Hozzáférés a beépített Input* összetevőkhöz.

A Blazor projektsablonból létrehozott projekt tartalmazza az alkalmazás _Imports.razor fájljában lévő névteret, így a névtér elérhetővé válik az alkalmazás Razor összetevői számára.

A szabványos HTML-űrlapok támogatottak. Hozzon létre egy űrlapot a normál HTML-<form> címkével, és adjon meg egy @onsubmit kezelőt a beküldött űrlapkérelem kezeléséhez.

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

Az előző StarshipPlainForm összetevőben:

• Az űrlap ott jelenik meg, ahol a <form> elem megjelenik. Az űrlap neve a @formname direktíva attribútummal van elnevezve, amely egyedileg azonosítja az űrlapot a Blazor keretrendszerben.
• A modell az összetevő @code blokkjában jön létre, és egy nyilvános tulajdonságban (Model) található. A [SupplyParameterFromForm] attribútum azt jelzi, hogy a társított tulajdonság értékét az űrlapadatokból kell megadni. A kérelem azon adatai, amelyek megegyeznek a tulajdonság nevével, a tulajdonsághoz lesznek kötve.
• A InputText összetevő egy bemeneti összetevő a sztringértékek szerkesztéséhez. A @bind-Value irányelv attribútum a Model.Id modelltulajdonságot az InputText összetevő Value tulajdonságához köti.
• A Submit metódus a @onsubmit visszahívás kezelőjeként van regisztrálva. A rendszer meghívja a kezelőt, amikor a felhasználó beküldi az űrlapot.

Fontos

Mindig használja a @formname direktíva attribútumot egyedi űrlapnévvel.

Blazor a kérés elfogásával javítja az oldalnavigációt és az űrlapkezelést, hogy a választ a meglévő DOM-ra alkalmazza, és a lehető legtöbb renderelt űrlapot megőrizze. A fejlesztés elkerüli az oldal teljes betöltését, és sokkal zökkenőmentesebb felhasználói élményt nyújt, hasonlóan az egyoldalas alkalmazáshoz (SPA), bár az összetevő a kiszolgálón jelenik meg. További információért lásd: ASP.NET Core Blazor útválasztás és navigáció.

Streaming renderelés egyszerű HTML-űrlapoknál támogatott. Vegye figyelembe, hogy űrlapok POSThasználatakor csak az űrlap kezelőin belüli DOM-frissítések lesznek streamelve (például @onsubmit). A OnInitializedAsync frissítések csak a GET kérések esetében lesznek streamelve. További információt a POST-válaszok betöltési fázisának engedélyezése (dotnet/aspnetcore #50994) című témakörben talál.

Jegyzet

A .NET referenciaforrásra mutató dokumentációs hivatkozások általában betöltik az adattár alapértelmezett ágát, amely a .NET következő kiadásának aktuális fejlesztését jelöli. Egy adott kiadás címkéjének kiválasztásához használja az Ágak vagy címkék legördülő menüt. További információ: A ASP.NET Core-forráskód (dotnet/AspNetCore.Docs #26205) verziócímkéjének kiválasztása.

Az előző példa az űrlapba beiktatott AntiforgeryToken összetevővel támogatja a hamisítás elleni védelmet. Az Antiforgery támogatás részleteit a cikk Antiforgery támogatás szakaszában találhatja meg.

Ha egy űrlapot egy másik elem DOM-eseményei alapján szeretne elküldeni, például oninputonblurJavaScript használatával küldje el az űrlapot (submit).

Ahelyett, hogy egyszerű űrlapokat használnál Blazor alkalmazásokban, az űrlapokat általában a Blazorbeépített űrlaptámogatásával, a keretrendszernek a EditForm összetevőjét használva definiálják. Az alábbi Razor összetevő bemutatja a tipikus elemeket, összetevőket és Razor kódot egy webforma EditForm összetevő használatával történő megjelenítéséhez.

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

Az előző Starship1 összetevőben:

• A EditForm összetevő ott jelenik meg, ahol a <EditForm> elem megjelenik. Az űrlap neve a FormName tulajdonsággal van elnevezve, amely egyedileg azonosítja az űrlapot a Blazor-keretrendszerben.
• A modell az összetevő @code blokkjában jön létre, és egy nyilvános tulajdonságban (Model) található. A tulajdonság a EditForm.Model paraméterhez van rendelve. A [SupplyParameterFromForm] attribútum azt jelzi, hogy a társított tulajdonság értékét az űrlapadatokból kell megadni. A kérelem azon adatai, amelyek megegyeznek a tulajdonság nevével, a tulajdonsághoz lesznek kötve.
• A InputText összetevő egy bemeneti összetevő, a sztringértékek szerkesztéséhez. A @bind-Value irányelv attribútum a Model.Id modelltulajdonságot az InputText összetevő Value tulajdonságához köti.
• A Submit metódus a OnSubmit visszahívás kezelőjeként van regisztrálva. A rendszer meghívja a kezelőt, amikor a felhasználó beküldi az űrlapot.

Fontos

Mindig egyedi űrlapnévvel használja a FormName tulajdonságot.

Blazor javítja a lapnavigációt és az űrlapkezelést EditForm összetevők esetében. További információért lásd: ASP.NET Core Blazor útválasztás és navigáció.

streameléses renderelés van támogatva a EditForm. Vegye figyelembe, hogy űrlapok POSThasználatakor csak az űrlap kezelőin belüli DOM-frissítések lesznek streamelve (például OnValidSubmit). A OnInitializedAsync frissítések csak a GET kérések esetében lesznek streamelve. További információt a POST-válaszok betöltési fázisának engedélyezése (dotnet/aspnetcore #50994) című témakörben talál.

Jegyzet

A .NET referenciaforrásra mutató dokumentációs hivatkozások általában betöltik az adattár alapértelmezett ágát, amely a .NET következő kiadásának aktuális fejlesztését jelöli. Egy adott kiadás címkéjének kiválasztásához használja az Ágak vagy címkék legördülő menüt. További információ: A ASP.NET Core-forráskód (dotnet/AspNetCore.Docs #26205) verziócímkéjének kiválasztása.

† További információ a tulajdonságkötésekről lásd: ASP.NET Core Blazor adatkötések.

A következő példában az előző összetevő módosul, hogy létrehozza az űrlapot a Starship2 összetevőben:

• OnSubmit-t OnValidSubmit váltja fel, amely feldolgozza a hozzárendelt eseménykezelőt, ha az űrlap érvényes, amikor a felhasználó beküldi.
• A rendszer hozzáad egy ValidationSummary összetevőt az érvényesítési üzenetek megjelenítéséhez, ha az űrlap érvénytelen az űrlap beküldésekor.
• Az adatjegyzet-érvényesítő (DataAnnotationsValidator összetevő†) adatjegyzetek használatával csatolja az érvényesítési támogatást:
  • Ha a <input> űrlapmező üresen marad a Submit gomb kiválasztásakor, hiba jelenik meg az érvényesítési összegzésben (ValidationSummary komponens‡) ("The Id field is required."), és Submitnem hívja meg a(z)-t.
  • Ha a <input> űrlapmező tíznél több karaktert tartalmaz a Submit gomb kiválasztásakor, hiba jelenik meg az érvényesítési összegzésben ("Id is too long."). Submit nincs hívva.
  • Ha a <input> űrlapmező érvényes értéket tartalmaz a Submit gomb kiválasztásakor, Submit lesz meghívva.

†Az DataAnnotationsValidator összetevőt az Validator összetevő szakasz ismerteti. ‡A ValidationSummary összetevőt az Érvényesítési összefoglaló és érvényesítési üzenet összetevői szakaszban találja.

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

Űrlapküldés kezelése

A EditForm a következő visszahívásokat biztosítja az űrlapküldés kezeléséhez:

• A OnValidSubmit használatával eseménykezelőt rendelhet a futtatáshoz érvényes mezőkkel rendelkező űrlap elküldésekor.
• A OnInvalidSubmit használatával eseménykezelőt rendelhet a futtatáshoz, ha érvénytelen mezőket tartalmazó űrlapot küld el.
• Az OnSubmit használatával eseménykezelőt rendelhet a futtatáshoz, függetlenül az űrlapmezők érvényesítési állapotától. Az űrlap érvényesítése EditContext.Validate meghívásával történik az eseménykezelő metódusban. Ha Validatetruead vissza, az űrlap érvényes.

Űrlap vagy mező törlése

Az űrlapot úgy állíthatja vissza, hogy a modell alapértelmezett állapotába kerül, amelyet a EditForm jelölésben vagy azon kívül is végrehajthat.

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

...

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

Másik lehetőségként használjon explicit Razor kifejezést:

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

Állítsa vissza a mezőt az eredeti állapotába a modell értékének törlésével.

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

...

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

Másik lehetőségként használjon explicit Razor kifejezést:

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

Az előző példákban nem kell meghívni StateHasChanged, mert a StateHasChanged keretrendszer automatikusan meghívja Blazor az összetevő újrarendezéséhez az eseménykezelő meghívása után. Ha egy eseménykezelő nem használja az űrlapot vagy mezőt törölő metódusok meghívását, akkor a fejlesztői kódnak meg kell hívnia StateHasChanged az összetevő újrarendeléséhez.

Hamisítás elleni támogatás

Az antiforgery szolgáltatások automatikusan hozzáadódnak a Blazor alkalmazásokhoz, amikor a AddRazorComponents fájlban a Program hívásra kerül.

Az alkalmazás az Antiforgery Middleware-t használja, meghívva a UseAntiforgery-t a kérésfeldolgozási folyamatában a Program fájlban. UseAntiforgery hívása a UseRoutinghívása után történik. Ha vannak hívások a UseRouting és a UseEndpointsszámára, akkor a UseAntiforgery hívásának UseRouting és UseEndpointsközött kell megtörténnie. A UseAntiforgery hívását UseAuthentication és UseAuthorizationhívása után kell végrehajtani.

A AntiforgeryToken összetevő rejtett mezőként jeleníti meg az antiforgery tokent, és a [RequireAntiforgeryToken] attribútum engedélyezi az antiforgery védelmet. Ha egy antiforgery-ellenőrzés sikertelen, a rendszer 400 - Bad Request választ ad, és az űrlap nem lesz feldolgozva.

A EditFormalapuló űrlapok esetében a rendszer automatikusan hozzáadja a AntiforgeryToken összetevőt és [RequireAntiforgeryToken] attribútumot az antiforgery elleni védelem érdekében.

A HTML-<form> elemen alapuló űrlapok esetében manuálisan adja hozzá a AntiforgeryToken összetevőt az űrlaphoz:

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

Figyelmeztetés

A EditForm vagy a HTML <form> elemre alapuló űrlapok esetén az antiforgery védelem letiltható, ha required: false-őt adunk át a [RequireAntiforgeryToken] attribútumnak. A következő példa letiltja az hamisítás-elleni védelmet, és nem ajánlott nyilvános applikációkhoz:

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

További információért lásd: ASP.NET Core Blazor hitelesítés és engedélyezés.

A túlpostolásos támadások enyhítése

A statikusan renderelt kiszolgálóoldali űrlapok, például az olyan összetevőkben, amelyek űrlapmodellel rendelkező adatbázis rekordjait hozzák létre és szerkesztik, sebezhetők lehetnek egy túlpostazó támadással szemben, más néven tömeges hozzárendelési támadással szemben. A túlpostolásos támadás akkor fordul elő, ha egy rosszindulatú felhasználó egy POST HTML-űrlapot ad ki a kiszolgálónak, amely olyan tulajdonságok adatait dolgozza fel, amelyek nem részei a renderelt űrlapnak, és hogy a fejlesztő nem kívánja engedélyezni a felhasználók számára a módosítást. A "túl sok posztolás" kifejezés szó szerint azt jelenti, hogy a rosszindulatú felhasználó túllépett az űrlappal történő posztoláskor, alkalommal ahelyett.

A túlfoglalás nem okoz problémát, ha a modell nem tartalmaz korlátozott tulajdonságokat a létrehozási és frissítési műveletekhez. Amikor statikus, SSR-alapú Blazor űrlapokat használ, amelyeket Ön tart karban, fontos szem előtt tartani a túlpostolást.

A túlpostolás csökkentése érdekében javasoljuk, hogy hozzon létre (beszúrási) és frissítési műveletekkel egy külön nézetmodellt/adatátviteli objektumot (DTO) az űrlaphoz és az adatbázishoz. Az űrlap elküldésekor az összetevő és a C# kód csak a nézetmodell/DTO tulajdonságait használja az adatbázis módosításához. A rosszindulatú felhasználó által küldött extra adatok elvetésre kerülnek, így a rosszindulatú felhasználó nem hajthat végre túlpostolási támadást.

Továbbfejlesztett űrlapkezelés

A POST űrlapkérések navigációs javítása Enhance űrlapok EditForm paraméterével vagy a HTML-űrlapok data-enhance attribútumával (<form>):

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

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

❌ Nem támogatott: Az űrlap elődelemén nem állíthat be továbbfejlesztett navigációt a továbbfejlesztett űrlapkezelés engedélyezéséhez.

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

A továbbfejlesztett űrlapbejegyzések csak Blazor végpontokkal működnek. A továbbfejlesztett űrlap nemBlazor végpontra való közzététele hibát eredményez.

A továbbfejlesztett űrlapkezelés letiltása:

• Egy EditFormesetén távolítsa el a Enhance paramétert az űrlapelemből (vagy állítsa false: Enhance="false").
• HTML-<form>esetén távolítsa el a data-enhance attribútumot az űrlapelemből (vagy állítsa false: data-enhance="false").

BlazorA továbbfejlesztett navigáció és űrlapkezelés visszavonhatja a DOM dinamikus módosításait, ha a frissített tartalom nem része a kiszolgáló renderelésének. Egy elem tartalmának megőrzéséhez használja a data-permanent attribútumot.

Az alábbi példában a <div> elem tartalmát egy szkript dinamikusan frissíti az oldal betöltésekor:

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

Ha globálisan szeretné letiltani a továbbfejlesztett navigációt és űrlapkezelést, olvassa el az ASP.NET Core Blazor indításról szóló részt.

A enhancedload esemény továbbfejlesztett lapfrissítések figyeléséhez való használatával kapcsolatos útmutatásért tekintse meg ASP.NET Core Blazor útválasztási és navigációscímű témakört.

Példák

A példák nem vezetnek be továbbfejlesztett űrlapkezelést az űrlap POST-kérelmekhez, de az összes példa frissíthető a továbbfejlesztett funkciók bevezetéséhez a Továbbfejlesztett űrlapkezelés című szakaszban található útmutatást követve.

Annak bemutatásához, hogy az űrlapok hogyan működnek érvényesítés során. Ha el szeretné kerülni az adatjegyzeteket használó összetevők további kódsorát, tegye elérhetővé a névteret az alkalmazás összetevői között az importálási fájllal (_Imports.razor):

@using System.ComponentModel.DataAnnotations

Példák a Star Trek univerzum aspektusaira. A Star Trek szerzői jog ©1966-2023 a CBS Studios és a Paramount tulajdona.

Az ügyféloldali ellenőrzéshez áramkör szükséges.

Az Blazor Web App-ek esetében az ügyféloldali ellenőrzéshez aktív BlazorSignalR kapcsolatcsoport szükséges. Az ügyféloldali ellenőrzés nem érhető el a statikus kiszolgálóoldali renderelést (statikus SSR) használó összetevők űrlapjai számára. A statikus SSR-t alkalmazó űrlapok az űrlap elküldése után érvényesítve lesznek a kiszolgálón.

Nem támogatott érvényesítési funkciók

A(z) adatjegyzet beépített érvényesítő támogatott a(z) Blazor rendszerben, kivéve a [Remote] érvényesítési attribútumot.

A jQuery érvényesítése nem támogatott Razor összetevőkben. Az alábbi módszerek bármelyikét javasoljuk:

• Kövesse az ASP.NET Core Blazor űrlapellenőrzési útmutatását az alábbi célok egyikére:
  • Kiszolgálóoldali érvényesítés egy interaktív renderelési módot alkalmazó Blazor Web App-ban.
  • Ügyféloldali érvényesítés különálló Blazor Web Assembly-alkalmazásban.
• Használjon natív HTML-érvényesítési attribútumokat (lásd az ügyféloldali űrlapérvényesítést).
• Harmadik féltől származó érvényesítési JavaScript-kódtár bevezetése.

A kiszolgálón statikusan renderelt űrlapok esetében az ügyféloldali érvényesítés új mechanizmusát kell figyelembe venni. További információkért tekintse meg A kiszolgáló által renderelt űrlapok létrehozása ügyfélérvényesítéssel Blazor kapcsolatcsoport nélkül (dotnet/aspnetcore #51040).

További erőforrások

• ASP.NET Core Blazor fájlok feltöltése
• Blazor GitHub-adattár mintái (dotnet/blazor-samples) (hogyan lehet letölteni)
• ASP.NET Core GitHub-adattár (dotnet/aspnetcore) tartalmazza a tesztelési elemeket