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 Validierung das Aktualisieren der CSS-Klasse des Feldes, um den Feldstatus als gültig oder ungültig mit dem Validierungsstil des zugrunde liegenden HTML-Elements anzugeben.
• Für Steuerelemente, die kein EditContext haben, spiegelt die Standardüberprüfung den gültigen oder ungültigen Status wider, bietet aber keine Überprüfugnsformatierung für das zugrunde liegende HTML-Element.

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).

Die Komponente InputNumber<TValue> unterstützt das Attribut type="range", mit dem eine Bereichseingabe erstellt wird, die Modellbindung und Formularprüfung unterstützt und in der Regel als Schieberegler oder Wählscheibe und nicht als Textfeld dargestellt wird:

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

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

Beispielformular

Der folgende Starship-Typ, der in mehreren Beispielen dieses Artikels und in Beispielen anderer Artikel zum Formulare-Knoten verwendet wird, definiert eine Vielzahl von 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:

• Die im vorherigen Modell Starship definierten Eigenschaften und Validierungen.
• Mehrere der in Blazor integrierten 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 Status des Clients durch den Status des Servers überschrieben, was normalerweise bedeutet, dass keine Option als ausgewählt markiert wird. Durch die Einstellung der markierten 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.
• Die Protokollierung wird abhängig vom Ergebnis der Validierung durchgefü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 void Submit()
    {
        if (editContext != null && editContext.Validate())
        {
            Logger.LogInformation("Submit: Form is valid");
        }
        else
        {
            Logger.LogInformation("Submit: Form is INVALID");
        }
    }
}

Hinweis

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

Auswahl mehrerer Optionen mit der Komponente InputSelect

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, der dazu führt, dass die InputSelect<TValue> Komponente das multiple Attribut automatisch dem <select> Element hinzufügt, wenn die Komponente gerendert wird.

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

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 beim Übermitteln des Formulars ein ungültiges Datum enthält, wird in der Fehlermeldung kein freundlicher Name 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.

Setzen Sie die DisplayName-Eigenschaft auf einen benutzerfreundlichen Namen mit einem Leerzeichen zwischen den Wörtern „Production“ und „Date“.

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

Die Validierungszusammenfassung zeigt den freundlichen Namen 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.

InputHidden Komponente zum Behandeln ausgeblendeter Eingabefelder in Formularen

Die InputHidden Komponente stellt ein ausgeblendetes Eingabefeld zum Speichern von Zeichenfolgenwerten bereit.

Im folgenden Beispiel wird ein ausgeblendetes Eingabefeld für die Eigenschaft des Formulars Parameter erstellt. Wenn das Formular übermittelt wird, wird der Wert des ausgeblendeten Felds angezeigt:

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