ASP.NET Core Blazor-Eingabekomponenten

In diesem Artikel werden die integrierten Eingabekomponenten von Blazor beschrieben.

Eingabekomponenten

Das Blazor-Framework bietet integrierte Eingabekomponenten zum Empfangen und Überprüfen von Benutzereingaben. Die integrierten Eingabekomponenten in der folgenden Tabelle werden in einem EditForm mit einem EditContext unterstützt.

Die Komponenten in der Tabelle werden auch außerhalb eines Formulars im Razor-Komponentenmarkup unterstützt. Eingaben werden validiert, wenn sie geändert werden und wenn ein Formular gesendet wird.

Eingabekomponenten	Wird gerendert als...
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>	Gruppe untergeordneter InputRadio<TValue>
InputSelect<TValue>	<select>
InputText	<input>
InputTextArea	<textarea>

Weitere Informationen zur Komponente InputFile finden Sie unter Blazor-Dateiuploads in ASP.NET Core.

Alle Eingabekomponenten einschließlich EditForm unterstützen arbiträre Attribute. Attribute, die nicht mit einem Komponentenparameter übereinstimmen, werden dem gerenderten HTML-Element hinzugefügt.

Eingabekomponenten weisen ein Standardverhalten für die Überprüfung auf, wenn ein Feld geändert wird:

• Bei Eingabekomponenten in einem Formular mit einem EditContext-Parameter beinhaltet das Standardverhalten bei der Überprüfung das Aktualisieren der CSS-Feldklasse, um den Feldstatus als gültig oder ungültig im Stil des zugrunde liegenden HTML-Elements anzugeben.
• Bei Steuerelementen ohne EditContext-Parameter gibt die Standardüberprüfung den Status als gültig oder ungültig an, aber wendet nicht den Stil des zugrunde liegenden HTML-Elements an.

Einige Komponenten beinhalten hilfreiche Parsinglogik. InputDate<TValue> und InputNumber<TValue> verarbeiten beispielsweise nicht parsbare Werte ordnungsgemäß, indem nicht parsbare Werte als Validierungsfehler registriert werden. Typen, die NULL-Werte akzeptieren, unterstützen auch die NULL-Zulässigkeit des Zielfelds (z. B. int? für eine Nullwerte zulassende ganze Zahl).

Weitere Informationen zur Komponente InputFile finden Sie unter Blazor-Dateiuploads in ASP.NET Core.

Beispielformular

Der folgende Starship-Typ, der in mehreren Beispielen und Beispielen in diesem Artikel und in Beispielen anderer Artikel zum Formularknoten verwendet wird, definiert verschiedene Eigenschaften mit Datenanmerkungen:

• Id ist erforderlich, da es mit dem RequiredAttribute kommentiert ist. Id erfordert einen Wert von mindestens einem Zeichen, aber nicht mehr als 16 Zeichen unter Verwendung des StringLengthAttribute.
• Description ist optional, da es nicht mit dem RequiredAttribute kommentiert ist.
• Classification ist erforderlich.
• Die MaximumAccommodation-Eigenschaft ist standardmäßig auf 0 festgelegt, erfordert aber einen Wert zwischen 1 und 100.000 pro RangeAttribute.
• IsValidatedDesign erfordert, dass die Eigenschaft einen Wert von true besitzt, was einem ausgewählten Zustand entspricht, wenn die Eigenschaft an ein Kontrollkästchen in der Benutzeroberfläche gebunden ist (<input type="checkbox">).
• ProductionDate ist ein DateTime-Wert und erforderlich.

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

Das folgende Formular akzeptiert und überprüft Benutzereingaben mit:

• Den im vorherigen Modell Starship definierten Eigenschaften und Überprüfungen.
• Mehreren der in Blazorintegrierten Eingabekomponenten

Wenn die Modelleigenschaft für die Schiffsklassifizierung (Classification) festgelegt wird, wird die Option überprüft, die dem Modell entspricht. Zum Beispiel checked="@(Model!.Classification == "Exploration")" für die Klassifizierung eines Erkundungsschiffs. Der Grund für das explizite Festlegen der aktivierten Option ist, dass der Wert eines <select>-Elements nur im Browser vorhanden ist. Wenn das Formular nach dem Absenden auf dem Server gerendert wird, wird der Zustand des Clients durch den Zustand des Servers überschrieben, der normalerweise keine Option als aktiviert markiert. Durch Festlegen der aktivierten Option aus der Modelleigenschaft spiegelt die Klassifizierung immer den Zustand des Modells wider. Dadurch wird die Klassifizierungsauswahl über Formularübermittlungen hinweg beibehalten, die dazu führen, dass das Formular auf dem Server erneut gerendert wird. In Situationen, in denen das Formular nicht auf dem Server erneut gerendert wird, z. B. wenn der Interaktive Server-Rendermodus direkt auf die Komponente angewendet wird, ist die explizite Zuweisung der aktivierten Option aus dem Modell nicht erforderlich, da Blazor den Zustand für das <select>-Element auf dem Client beibehält.

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

EditForm im vorherigen Beispiel erstellt einen EditContext auf Grundlage der zugewiesenen Starship-Instanz (Model="...") und behandelt ein gültiges Formular. Das nächste Beispiel veranschaulicht, wie einem Formular ein EditContext zugewiesen und bei der Formularübermittlung überprüft wird.

Im folgenden Beispiel:

• Es wird eine verkürzte Version des vorangehenden Starfleet Starship Database-Formulars (Starship3-Komponente) verwendet, das nur einen Wert für die ID des „Starship“ akzeptiert. Die anderen Starship-Eigenschaften erhalten gültige Standardwerte, wenn eine Instanz des Starship-Typs erstellt wird.
• Die Submit-Methode wird ausgeführt, wenn die Schaltfläche Submit ausgewählt wird.
• Das Formular wird durch Aufrufen von EditContext.Validate in der Submit-Methode überprüft.
• Protokollierung wird abhängig vom Validierungsergebnis ausgeführt.

Hinweis

Das nächste Beispiel veranschaulicht Submit als asynchrone Methode, da beim Speichern von Formularwerten häufig asynchrone Aufrufe (await ...) verwendet werden. Wenn das Formular wie gezeigt in einer Test-App verwendet wird, wird Submit nur synchron ausgeführt. Ignorieren Sie zu Testzwecken die folgende Buildwarnung:

Bei dieser asynchronen Methode fehlen „await“-Operatoren. Die Methode wird synchron ausgeführt. ...

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 async Task Submit()
    {
        if (editContext != null && editContext.Validate())
        {
            Logger.LogInformation("Submit called: Form is valid");

            // await ...
        }
        else
        {
            Logger.LogInformation("Submit called: Form is INVALID");
        }
    }
}

Hinweis

Das Ändern von EditContext nach der Zuweisung wird nicht unterstützt.

Auswahl der Option „multiple“ mit der InputSelect-Komponente

Die Bindung unterstützt die Auswahl der Option multiple für die InputSelect<TValue>-Komponente. Das @onchange-Ereignis stellt ein Array der ausgewählten Optionen über Ereignisargumente (ChangeEventArgs) bereit. Der Wert muss an einen Arraytyp gebunden werden, und durch Bindung an einen Arraytyp wird das multiple-Attribut für das InputSelect<TValue>-Tag optional.

Im folgenden Beispiel muss der Benutzer mindestens zwei Starship-Klassifizierungen, aber nicht mehr als drei Klassifizierungen auswählen.

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 called: Processing the 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; } =
            new[] { Classification.None };
    }

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

Informationen dazu, wie leere Zeichenfolgen und null-Werte in der Datenbindung behandelt werden, finden Sie im Abschnitt Binden von InputSelect-Optionen an null-Werte von C#-Objekten.

Binden von InputSelect-Optionen an null-Werte von C#-Objekten

Informationen dazu, wie leere Zeichenfolgen und null-Werte in der Datenbindung behandelt werden, finden Sie unter Blazor-Datenbindung in ASP.NET Core.

Unterstützung für Anzeigenamen

Mehrere integrierte Komponenten unterstützen Anzeigenamen mit dem InputBase<TValue>.DisplayName-Parameter.

Im Starfleet Starship Database-Formular (Starship3-Komponente) des Abschnitts Beispielformular gibt das Produktionsdatum eines neuen „Starship“ keinen Anzeigenamen an:

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

Wenn das Feld ein ungültiges Datum enthält, wenn das Formular übermittelt wird, wird in der Fehlermeldung kein Anzeigename angezeigt. Der Feldname „ProductionDate“ besitzt kein Leerzeichen zwischen „Production“ und „Date“, wenn er in der Validierungszusammenfassung angezeigt wird:

Das Feld „ProductionDate“ (Produktionsdatum) muss ein Datum sein.

Legen Sie die DisplayName-Eigenschaft auf einen Anzeigenamen mit einem Leerzeichen zwischen den Wörtern „Production“ und „Date“ fest:

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

Die Validierungszusammenfassung zeigt den Anzeigenamen an, wenn der Wert des Felds ungültig ist:

Das Feld „ProductionDate“ (Produktionsdatum) muss ein Datum sein.

Unterstützung für Fehlermeldungsvorlagen

InputDate<TValue> und InputNumber<TValue> unterstützen Fehlermeldungsvorlagen:

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

Im Starfleet Starship Database-Formular (Starship3-Komponente) des Abschnitts Beispielformular mit zugewiesenem Anzeigenamen erzeugt das Production Date-Feld mithilfe der folgenden Standardfehlermeldungsvorlage eine Fehlermeldung:

The {0} field must be a date.

Die Position des {0}-Platzhalters ist die Stelle, an der der Wert der DisplayName-Eigenschaft angezeigt wird, wenn der Fehler dem Benutzer angezeigt wird.

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

Das Feld „ProductionDate“ (Produktionsdatum) muss ein Datum sein.

Weisen Sie ParsingErrorMessage eine benutzerdefinierte Vorlage zu, um eine benutzerdefinierte Meldung bereitzustellen:

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

Das Feld „ProductionDate“ (Produktionsdatum) weist einen falschen Datumswert auf.