Panoramica dei moduli di Blazor base di ASP.NET

Questo articolo illustra come usare i moduli in Blazor.

Componenti e moduli di input

Il Blazor framework supporta i moduli e fornisce componenti di input predefiniti:

• Associato a un oggetto o a un modello che può usare annotazioni di dati
  • Moduli HTML con l'elemento <form>
  • Componenti di EditForm
• Componenti di input predefiniti

Lo Microsoft.AspNetCore.Components.Forms spazio dei nomi fornisce:

• Classi per la gestione di elementi del modulo, stato e convalida.
• Accesso ai componenti predefiniti Input* .

Un progetto creato dal Blazor modello di progetto include lo spazio dei nomi per impostazione predefinita nel file dell'app _Imports.razor , che rende lo spazio dei nomi disponibile per i componenti dell'app Razor .

I moduli HTML standard sono supportati. Creare un modulo usando il normale tag HTML <form> e specificare un @onsubmit gestore per la gestione della richiesta di modulo inviata.

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

Nel componente precedente StarshipPlainForm :

• Viene eseguito il rendering del modulo in cui viene visualizzato l'elemento <form> . Il form viene denominato con l'attributo @formname di direttiva , che identifica in modo univoco il modulo nel Blazor framework.
• Il modello viene creato nel blocco del @code componente e mantenuto in una proprietà pubblica (Model). L'attributo [SupplyParameterFromForm] indica che il valore della proprietà associata deve essere fornito dai dati del modulo. I dati nella richiesta che corrispondono al nome della proprietà vengono associati alla proprietà .
• Il InputText componente è un componente di input per la modifica dei valori stringa. L'attributo @bind-Value della direttiva associa la Model.Id proprietà del modello alla InputText proprietà del Value componente.
• Il Submit metodo viene registrato come gestore per il @onsubmit callback. Il gestore viene chiamato quando il modulo viene inviato dall'utente.

Importante

Usare sempre l'attributo @formname di direttiva con un nome di modulo univoco.

Blazor migliora lo spostamento delle pagine e la gestione dei moduli intercettando la richiesta per applicare la risposta al DOM esistente, mantenendo la maggior parte possibile del modulo sottoposto a rendering. Il miglioramento evita la necessità di caricare completamente la pagina e offre un'esperienza utente molto più fluida, simile a un'app a pagina singola (SPA), anche se il rendering del componente viene eseguito nel server. Per altre informazioni, vedere ASP.NET routing e navigazione coreBlazor.

Il rendering in streaming è supportato per i moduli HTML semplici.

Nota

I collegamenti della documentazione all'origine del riferimento .NET in genere caricano il ramo predefinito del repository, che rappresenta lo sviluppo corrente per la versione successiva di .NET. Per selezionare un tag per una versione specifica, usare l'elenco a discesa Switch branches or tags. Per altre informazioni, vedere How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205) (Come selezionare un tag di versione del codice sorgente di ASP.NET - dotnet/AspNetCore.Docs #26205).

L'esempio precedente include il supporto antiforgery includendo un AntiforgeryToken componente nel modulo. Il supporto antiforgery è illustrato più avanti nella sezione supporto antiforgery di questo articolo.

Per inviare un modulo in base agli eventi DOM di un altro elemento, ad esempio oninput o , usare JavaScript per inviare il modulo (submit (documentazione MDN)onblur).

Invece di usare moduli normali nelle Blazor app, un modulo viene in genere definito con Blazoril supporto predefinito del modulo usando il componente del EditForm framework. Il componente seguente Razor illustra elementi, componenti e Razor codice tipici per eseguire il rendering di una webform usando un EditForm componente.

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

Nel componente precedente Starship1 :

• Viene eseguito il rendering del EditForm componente in cui viene visualizzato l'elemento <EditForm> . Il form viene denominato con l'attributo @formname di direttiva , che identifica in modo univoco il modulo nel Blazor framework.
• Il modello viene creato nel blocco del @code componente e mantenuto in una proprietà pubblica (Model). La proprietà viene assegnata al EditForm.Model parametro . L'attributo [SupplyParameterFromForm] indica che il valore della proprietà associata deve essere fornito dai dati del modulo. I dati nella richiesta che corrispondono al nome della proprietà vengono associati alla proprietà .
• Il InputText componente è un componente di input per la modifica dei valori stringa. L'attributo @bind-Value della direttiva associa la Model.Id proprietà del modello alla InputText proprietà del Value componente.
• Il Submit metodo viene registrato come gestore per il OnSubmit callback. Il gestore viene chiamato quando il modulo viene inviato dall'utente.

Importante

Usare sempre l'attributo @formname di direttiva con un nome di modulo univoco.

Blazor migliora lo spostamento delle pagine e la gestione dei moduli per EditForm i componenti. Per altre informazioni, vedere ASP.NET routing e navigazione coreBlazor.

Il rendering di streaming è supportato per EditForm.

Nota

I collegamenti della documentazione all'origine del riferimento .NET in genere caricano il ramo predefinito del repository, che rappresenta lo sviluppo corrente per la versione successiva di .NET. Per selezionare un tag per una versione specifica, usare l'elenco a discesa Switch branches or tags. Per altre informazioni, vedere How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205) (Come selezionare un tag di versione del codice sorgente di ASP.NET - dotnet/AspNetCore.Docs #26205).

†Per altre informazioni sull'associazione di proprietà, vedere ASP.NET Data Binding coreBlazor.

Nell'esempio successivo, il componente precedente viene modificato per creare il modulo nel Starship2 componente:

• OnSubmit viene sostituito con OnValidSubmit, che elabora il gestore eventi assegnato se il modulo è valido quando inviato dall'utente.
• Viene aggiunto un ValidationSummary componente per visualizzare i messaggi di convalida quando il modulo non è valido per l'invio del modulo.
• Il validator delle annotazioni dati (DataAnnotationsValidator component†) associa il supporto per la convalida usando le annotazioni dei dati:
  • Se il <input> campo modulo viene lasciato vuoto quando si seleziona il Submit pulsante, viene visualizzato un errore nel riepilogo di convalida (ValidationSummary component**) ("The Id field is required.") e Submit non viene chiamato.
  • Se il <input> campo modulo contiene più di dieci caratteri quando si seleziona il Submit pulsante, viene visualizzato un errore nel riepilogo della convalida ("Id is too long."). Submitnon viene chiamato.
  • Se il <input> campo modulo contiene un valore valido quando si seleziona il Submit pulsante, Submit viene chiamato .

†Il DataAnnotationsValidator componente è trattato nella sezione Componente validator. *Il ValidationSummary componente è trattato nella sezione Riepilogo convalida e componenti del messaggio di convalida.

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

Gestire gli invii del modulo

Fornisce EditForm i callback seguenti per la gestione dell'invio di moduli:

• Utilizzare OnValidSubmit per assegnare un gestore eventi da eseguire quando viene inviato un modulo con campi validi.
• Utilizzare OnInvalidSubmit per assegnare un gestore eventi da eseguire quando viene inviato un modulo con campi non validi.
• Usare OnSubmit per assegnare un gestore eventi da eseguire indipendentemente dallo stato di convalida dei campi modulo. Il modulo viene convalidato chiamando EditContext.Validate nel metodo del gestore eventi. Se Validate restituisce true, il modulo è valido.

Cancellare un modulo o un campo

Reimpostare un modulo cancellando lo stato predefinito del modello, che può essere eseguito all'interno o all'esterno del markup di un EditFormoggetto :

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

...

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

In alternativa, usare un'espressione esplicita Razor :

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

Reimpostare un campo cancellando il valore del modello sullo stato predefinito:

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

...

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

In alternativa, usare un'espressione esplicita Razor :

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

Non è necessario chiamare StateHasChanged negli esempi precedenti perché StateHasChanged viene chiamato automaticamente dal framework per eseguire il Blazor rerendere il componente dopo che viene richiamato un gestore eventi. Se un gestore eventi non viene usato per richiamare i metodi che cancellano una maschera o un campo, il codice dello sviluppatore deve chiamare StateHasChanged per risolvere il problema.

Supporto antiforgerato

I servizi antiforgery vengono aggiunti automaticamente alle Blazor app quando AddRazorComponents viene chiamato nel Program file.

L'app usa il middleware antiforgery chiamando UseAntiforgery nella pipeline di elaborazione delle richieste nel Program file. UseAntiforgery viene chiamato dopo la chiamata a UseRouting. Se sono presenti chiamate a UseRouting e UseEndpoints, la chiamata a UseAntiforgery deve passare tra di esse. Una chiamata a UseAntiforgery deve essere effettuata dopo le chiamate a UseAuthentication e UseAuthorization.

Il componente esegue il AntiforgeryToken rendering di un token antiforgery come campo nascosto e l'attributo [RequireAntiforgeryToken] abilita la protezione antiforgeria. Se un controllo antiforgery ha esito negativo, viene generata una 400 - Bad Request risposta e il modulo non viene elaborato.

Per i moduli basati su EditForm, il componente e [RequireAntiforgeryToken] l'attributo AntiforgeryToken vengono aggiunti automaticamente per fornire protezione antiforgeria per impostazione predefinita.

Per i moduli basati sull'elemento HTML <form> , aggiungere manualmente il AntiforgeryToken componente al modulo:

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

Avviso

Per i moduli basati su uno EditForm o sull'elemento HTML <form> , la protezione antiforgery può essere disabilitata passando required: false all'attributo [RequireAntiforgeryToken] . L'esempio seguente disabilita l'antiforgeria e non è consigliato per le app pubbliche:

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

Per altre informazioni, vedere autenticazione e autorizzazione di base ASP.NETBlazor.

Gestione avanzata dei moduli

Migliorare la navigazione per le richieste POST del modulo con il Enhance parametro per EditForm i moduli o l'attributo data-enhance per i moduli HTML (<form>):

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

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

❌Non supportato: non è possibile impostare lo spostamento avanzato sull'elemento predecessore di un modulo per abilitare la gestione avanzata dei moduli.

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

I post di modulo avanzati funzionano solo con Blazor gli endpoint. La pubblicazione di un modulo avanzato in un endpoint diversoBlazor da un endpoint genera un errore.

Per disabilitare la gestione avanzata dei moduli:

• Per un EditFormoggetto , rimuovere il Enhance parametro dall'elemento del modulo (o impostarlo su false: Enhance="false").
• Per un codice HTML <form>, rimuovere l'attributo dall'elemento data-enhance form (o impostarlo su false: data-enhance="false").

BlazorSe il contenuto aggiornato non fa parte del rendering del server, la navigazione avanzata e la mano del modulo possono annullare modifiche dinamiche al DOM. Per mantenere il contenuto di un elemento, usare l'attributo data-permanent .

Nell'esempio seguente il contenuto dell'elemento <div> viene aggiornato dinamicamente da uno script quando la pagina viene caricata:

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

Per disabilitare l'esplorazione avanzata e la gestione dei moduli a livello globale, vedere ASP.NET avvio di CoreBlazor.

Per indicazioni sull'uso dell'evento per l'ascolto enhancedload degli aggiornamenti di pagina avanzati, vedere ASP.NET routing e navigazione coreBlazor.

Esempi

Gli esempi non adottano una gestione avanzata dei moduli per le richieste POST, ma tutti gli esempi possono essere aggiornati per adottare le funzionalità avanzate seguendo le indicazioni nella sezione Gestione avanzata dei moduli.

Per illustrare il funzionamento dei moduli con la convalida delle annotazioni dei dati, i componenti di esempio si basano sull'API System.ComponentModel.DataAnnotations . Se vuoi evitare una riga di codice aggiuntiva nei componenti che usano annotazioni di dati, rendi disponibile lo spazio dei nomi nei componenti dell'app con il file imports (_Imports.razor):

@using System.ComponentModel.DataAnnotations

Esempi di moduli fanno riferimento ad aspetti dell'universo di Star Trek . Star Trek è un copyright ©del 1966-2023 di CBS Studios e Paramount.

Risorse aggiuntive

• ASP.NET caricamenti di file di base Blazor
• Blazorrepository GitHub di esempi () (dotnet/blazor-samplescome scaricare)
• ASP.NET Core GitHub repository () form test assets (dotnet/aspnetcore)