ASP.NET componenti di input principali Blazor

Questo articolo descrive i Blazorcomponenti di input predefiniti.

Componenti di input

Il Blazor framework fornisce componenti di input predefiniti per ricevere e convalidare l'input dell'utente. I componenti di input predefiniti nella tabella seguente sono supportati in un EditForm con un EditContext.

I componenti della tabella sono supportati anche all'esterno di un modulo nel Razor markup dei componenti. Gli input vengono convalidati quando vengono modificati e quando viene inviato un modulo.

Componente di input	Reso come...
InputCheckbox	<input type="checkbox">
InputDate<TValue>	<input type="date">
InputFile	<input type="file">
InputNumber<TValue>	<input type="number">
InputRadio<TValue>	<input type="radio">
InputRadioGroup<TValue>	Gruppo di elementi figli InputRadio<TValue>
InputSelect<TValue>	<select>
InputText	<input>
InputTextArea	<textarea>

Per ulteriori informazioni sul componente InputFile, vedere caricamento di file in ASP.NET CoreBlazor.

Tutti i componenti di input, incluso EditForm, supportano attributi arbitrari. Qualsiasi attributo che non corrisponde a un parametro del componente viene aggiunto all'elemento HTML sottoposto a rendering.

I componenti di input forniscono un comportamento predefinito per la convalida quando viene modificato un campo:

• Per i componenti di input in un modulo con EditContext, il comportamento di convalida predefinito include l'aggiornamento della classe CSS del campo per riflettere lo stato del campo come valido o invalido, applicando lo stile di convalida all'elemento HTML sottostante.
• Per i controlli che non dispongono di un oggetto EditContext, la convalida predefinita riflette lo stato valido o non valido, ma non fornisce lo stile di convalida all'elemento HTML sottostante.

Alcuni componenti includono una logica di analisi utile. Ad esempio, InputDate<TValue> e InputNumber<TValue> gestiscono i valori non analizzabili in modo appropriato registrando i valori non analizzabili come errori di convalida. I tipi che possono accettare valori Null supportano la nullabilità del campo di destinazione, ad esempio int? per un numero intero nullable.

Il componente InputNumber<TValue> supporta l'attributo type="range", che crea un campo di input per intervallo che supporta l'associazione del modello e la convalida del modulo, in genere rappresentato come dispositivo di scorrimento o controllo di composizione anziché una casella di testo.

<InputNumber @bind-Value="..." max="..." min="..." step="..." type="range" />

Per ulteriori informazioni sul componente InputFile, vedere caricamento di file in ASP.NET CoreBlazor.

Modulo di esempio

Il tipo seguente Starship , che viene usato in diversi esempi di questo articolo ed esempi in altri articoli del nodo Forms , definisce un set diversificato di proprietà con annotazioni di dati:

• Idè obbligatorio perché viene annotato con .RequiredAttribute Idrichiede un valore di almeno un carattere, ma non più di 16 caratteri usando .StringLengthAttribute
• Descriptionè facoltativo perché non è annotato con .RequiredAttribute
• Classification è obbligatorio.
• Per impostazione predefinita, la MaximumAccommodation proprietà è zero, ma richiede un valore compreso tra uno e 100.000 per il relativo RangeAttribute.
• IsValidatedDesign richiede che la proprietà abbia un true valore, che corrisponde a uno stato selezionato quando la proprietà è associata a una casella di controllo nell'interfaccia utente (<input type="checkbox">).
• ProductionDate è un DateTime ed è obbligatorio.

Starship.cs:

using System.ComponentModel.DataAnnotations;

namespace BlazorSample;

public class Starship
{
    [Required]
    [StringLength(16, ErrorMessage = "Identifier too long (16 character limit).")]
    public string? Id { get; set; }

    public string? Description { get; set; }

    [Required]
    public string? Classification { get; set; }

    [Range(1, 100000, ErrorMessage = "Accommodation invalid (1-100000).")]
    public int MaximumAccommodation { get; set; }

    [Required]
    [Range(typeof(bool), "true", "true", ErrorMessage = "Approval required.")]
    public bool IsValidatedDesign { get; set; }

    [Required]
    public DateTime ProductionDate { get; set; }
}

Il modulo seguente accetta e convalida l'input dell'utente usando:

• Proprietà e convalida definite nel modello precedente Starship .
• Componenti di input predefiniti di Blazor.

Quando viene impostata la proprietà del modello per la classificazione della nave (Classification), viene selezionata l'opzione corrispondente al modello. Ad esempio, checked="@(Model!.Classification == "Exploration")" per la classificazione di una nave di esplorazione. Il motivo dell'impostazione esplicita dell'opzione selezionata è che il valore di un <select> elemento è presente solo nel browser. Se il rendering del modulo viene eseguito sul server dopo l'invio, qualsiasi stato del client viene completamente sostituito con lo stato dal server, il quale generalmente non seleziona un'opzione come contrassegnata. Impostando l'opzione selezionata dalla proprietà del modello, la classificazione riflette sempre lo stato del modello. In questo modo viene mantenuta la selezione della classificazione tra gli invii di moduli che comportano il ricaricamento del modulo sul server. In situazioni in cui il modulo non viene ririsolto nel server, ad esempio quando la modalità di rendering Interactive Server viene applicata direttamente al componente, l'assegnazione esplicita dell'opzione selezionata dal modello non è necessaria perché Blazor mantiene lo stato per l'elemento <select> nel client.

Starship3.razor:

@page "/starship-3"
@inject ILogger<Starship3> Logger

<h1>Starfleet Starship Database</h1>

<h2>New Ship Entry Form</h2>

<EditForm Model="Model" OnValidSubmit="Submit" FormName="Starship3">
    <DataAnnotationsValidator />
    <ValidationSummary />
    <div>
        <label>
            Identifier: 
            <InputText @bind-Value="Model!.Id" />
        </label>
    </div>
    <div>
        <label>
            Description (optional): 
            <InputTextArea @bind-Value="Model!.Description" />
        </label>
    </div>
    <div>
        <label>
            Primary Classification: 
            <InputSelect @bind-Value="Model!.Classification">
                <option value="">
                    Select classification ...
                </option>
                <option checked="@(Model!.Classification == "Exploration")" 
                    value="Exploration">
                    Exploration
                </option>
                <option checked="@(Model!.Classification == "Diplomacy")" 
                    value="Diplomacy">
                    Diplomacy
                </option>
                <option checked="@(Model!.Classification == "Defense")" 
                    value="Defense">
                    Defense
                </option>
            </InputSelect>
        </label>
    </div>
    <div>
        <label>
            Maximum Accommodation: 
            <InputNumber @bind-Value="Model!.MaximumAccommodation" />
        </label>
    </div>
    <div>
        <label>
            Engineering Approval: 
            <InputCheckbox @bind-Value="Model!.IsValidatedDesign" />
        </label>
    </div>
    <div>
        <label>
            Production Date: 
            <InputDate @bind-Value="Model!.ProductionDate" />
        </label>
    </div>
    <div>
        <button type="submit">Submit</button>
    </div>
</EditForm>

@code {
    [SupplyParameterFromForm]
    private Starship? Model { get; set; }

    protected override void OnInitialized() =>
        Model ??= new() { ProductionDate = DateTime.UtcNow };

    private void Submit()
    {
        Logger.LogInformation("Id = {Id} Description = {Description} " +
            "Classification = {Classification} MaximumAccommodation = " +
            "{MaximumAccommodation} IsValidatedDesign = " +
            "{IsValidatedDesign} ProductionDate = {ProductionDate}",
            Model?.Id, Model?.Description, Model?.Classification,
            Model?.MaximumAccommodation, Model?.IsValidatedDesign,
            Model?.ProductionDate);
    }
}

Nell'esempio EditForm precedente viene creato un oggetto EditContext basato sull'istanza assegnata Starship (Model="...") e viene gestito un modulo valido. Nell'esempio seguente viene illustrato come assegnare un oggetto EditContext a un modulo e convalidare quando viene inviato il modulo.

Nell'esempio seguente :

• Viene usata una versione abbreviata del formato precedente Starfleet Starship Database (Starship3 componente) che accetta solo un valore per l'ID della astronave. Le altre Starship proprietà ricevono valori predefiniti validi quando viene creata un'istanza del Starship tipo.
• Il Submit metodo viene eseguito quando il Submit pulsante è selezionato.
• Il modulo viene convalidato chiamando EditContext.Validate nel Submit metodo .
• La registrazione viene eseguita a seconda del risultato della convalida.

Starship4.razor:

@page "/starship-4"
@inject ILogger<Starship4> Logger

<EditForm EditContext="editContext" OnSubmit="Submit" FormName="Starship4">
    <DataAnnotationsValidator />
    <div>
        <label>
            Identifier: 
            <InputText @bind-Value="Model!.Id" />
        </label>
    </div>
    <div>
        <button type="submit">Submit</button>
    </div>
</EditForm>

@code {
    private EditContext? editContext;

    [SupplyParameterFromForm]
    private Starship? Model { get; set; }

    protected override void OnInitialized()
    {
        Model ??=
            new()
                {
                    Id = "NCC-1701",
                    Classification = "Exploration",
                    MaximumAccommodation = 150,
                    IsValidatedDesign = true,
                    ProductionDate = new DateTime(2245, 4, 11)
                };
        editContext = new(Model);
    }

    private void Submit()
    {
        if (editContext != null && editContext.Validate())
        {
            Logger.LogInformation("Submit: Form is valid");
        }
        else
        {
            Logger.LogInformation("Submit: Form is INVALID");
        }
    }
}

Nota

La modifica di EditContext dopo che è stata assegnata non è supportata.

Selezione di più opzioni con il InputSelect componente

Il binding supporta l'opzione di selezione con il componente multiple. L'evento @onchange fornisce una matrice delle opzioni selezionate tramite argomenti evento (ChangeEventArgs). Il valore deve essere associato a un tipo di array, il che comporta l'aggiunta automatica dell'attributo InputSelect<TValue>multiple all'elemento quando il componente viene renderizzato.

Nell’esempio seguente, l’utente deve selezionare almeno due categorie di astronavi, ma non più di tre categorie.

Starship5.razor:

@page "/starship-5"
@using System.ComponentModel.DataAnnotations
@inject ILogger<Starship5> Logger

<h1>Bind Multiple <code>InputSelect</code> Example</h1>

<EditForm EditContext="editContext" OnValidSubmit="Submit" FormName="Starship5">
    <DataAnnotationsValidator />
    <ValidationSummary />
    <div>
        <label>
            Select classifications (Minimum: 2, Maximum: 3):
            <InputSelect @bind-Value="Model!.SelectedClassification">
                <option value="@Classification.Exploration">Exploration</option>
                <option value="@Classification.Diplomacy">Diplomacy</option>
                <option value="@Classification.Defense">Defense</option>
                <option value="@Classification.Research">Research</option>
            </InputSelect>
        </label>
    </div>
    <div>
        <button type="submit">Submit</button>
    </div>
</EditForm>

@if (Model?.SelectedClassification?.Length > 0)
{
    <div>@string.Join(", ", Model.SelectedClassification)</div>
}

@code {
    private EditContext? editContext;

    [SupplyParameterFromForm]
    private Starship? Model { get; set; }

    protected override void OnInitialized()
    {
        Model = new();
        editContext = new(Model);
    }

    private void Submit() => Logger.LogInformation("Submit: Processing form");

    private class Starship
    {
        [Required]
        [MinLength(2, ErrorMessage = "Select at least two classifications.")]
        [MaxLength(3, ErrorMessage = "Select no more than three classifications.")]
        public Classification[]? SelectedClassification { get; set; } =
            [ Classification.None ];
    }

    private enum Classification { None, Exploration, Diplomacy, Defense, Research }
}

Per informazioni su come vengono gestite stringhe e null valori vuoti nel data binding, vedere la InputSelect degli oggetti null C#.

Collegamento delle opzioni InputSelect ai valori dell'oggetto null C#

Per informazioni su come vengono gestite le stringhe vuote e i valori nel data binding, vedere null.

Supporto per i nomi visualizzati

Diversi componenti predefiniti supportano nomi visuali con il parametro InputBase<TValue>.DisplayName.

Starfleet Starship Database Nel formato (Starship3 componente) della sezione Modulo di esempio, la data di produzione di una nuova astronave non specifica un nome visualizzato:

<label>
    Production Date:
    <InputDate @bind-Value="Model!.ProductionDate" />
</label>

Se il campo contiene una data non valida quando viene inviato il modulo, il messaggio di errore non visualizza un nome descrittivo. Il nome del campo "ProductionDate" non ha uno spazio tra "Production" e "Date" quando viene visualizzato nel riepilogo della convalida:

Il campo ProductionDate deve essere una data.

Imposta la proprietà DisplayName su un nome descrittivo che contenga uno spazio tra le parole "Production" e "Date":

<label>
    Production Date:
    <InputDate @bind-Value="Model!.ProductionDate" 
        DisplayName="Production Date" />
</label>

Il riepilogo della convalida visualizza il nome amichevole quando il valore del campo non è valido.

Il campo Data di produzione deve essere una data.

Supporto del modello di messaggio di errore

InputDate<TValue> e InputNumber<TValue> supportano i modelli di messaggio di errore:

• InputDate<TValue>.ParsingErrorMessage
• InputNumber<TValue>.ParsingErrorMessage

Nel Starfleet Starship Database modulo (Starship3 componente) della sezione Modulo di esempio con un nome descrittivo visualizzato assegnato, il Production Date campo genera un messaggio di errore usando il modello di messaggio di errore predefinito seguente:

The {0} field must be a date.

La posizione del {0} segnaposto è la posizione in cui viene visualizzato il valore della DisplayName proprietà quando l'errore viene visualizzato all'utente.

<label>
    Production Date:
    <InputDate @bind-Value="Model!.ProductionDate" 
        DisplayName="Production Date" />
</label>

Il campo Data di produzione deve essere una data.

Assegnare un modello personalizzato a ParsingErrorMessage per fornire un messaggio personalizzato.

<label>
    Production Date:
    <InputDate @bind-Value="Model!.ProductionDate" 
        DisplayName="Production Date" 
        ParsingErrorMessage="The {0} field has an incorrect date value." />
</label>

Il campo Data di produzione ha un valore di data non corretto.

InputHidden componente per gestire i campi di input nascosti nei moduli

Il InputHidden componente fornisce un campo di input nascosto per l'archiviazione dei valori stringa.

Nell'esempio seguente viene creato un campo di input nascosto per la proprietà del Parameter modulo. Quando viene inviato il modulo, viene visualizzato il valore del campo nascosto:

<EditForm Model="Parameter" OnValidSubmit="Submit" FormName="InputHidden Example">
    <InputHidden id="hidden" @bind-Value="Parameter" />
    <button type="submit">Submit</button>
</EditForm>

@if (submitted)
{
    <p>Hello @Parameter!</p>
}

@code {
    private bool submitted;

    [SupplyParameterFromForm] 
    public string Parameter { get; set; } = "stranger";

    private void Submit() => submitted = true;
}