składniki wejściowe ASP.NET Core Blazor

W tym artykule opisano Blazorwbudowane składniki wejściowe.

Składniki wejściowe

Platforma Blazor udostępnia wbudowane składniki wejściowe do odbierania i weryfikowania danych wejściowych użytkownika. Wbudowane składniki wejściowe w poniższej tabeli są obsługiwane w elemecie EditForm z elementem EditContext.

Składniki w tabeli są również obsługiwane poza formularzem w Razor adiustacji składników. Dane wejściowe są weryfikowane po zmianie i przesłaniu formularza.

Składnik wejściowy	Renderowane jako...
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>	Grupa elementów podrzędnych InputRadio<TValue>
InputSelect<TValue>	<select>
InputText	<input>
InputTextArea	<textarea>

Aby uzyskać więcej informacji na temat składnika InputFile, zobacz również Przekazywanie plików w ASP.NET CoreBlazor.

Wszystkie składniki wejściowe, w tym EditForm, obsługują dowolne atrybuty. Każdy atrybut, który nie pasuje do parametru składnika, jest dodawany do renderowanego elementu HTML.

Składniki wejściowe zapewniają domyślne zachowanie podczas sprawdzania poprawności po zmianie pola:

• W przypadku składników wejściowych w formularzu z EditContext, domyślne zachowanie walidacji obejmuje aktualizowanie klasy CSS pola w celu odzwierciedlenia stanu pola jako prawidłowego lub nieprawidłowego za pomocą stylizacji walidacyjnej podstawowego elementu HTML.
• W przypadku kontrolek, które nie mają elementu EditContext, domyślne sprawdzanie poprawności odzwierciedla prawidłowy lub nieprawidłowy stan, ale nie zapewnia weryfikacji stylu bazowego elementu HTML.

Niektóre składniki obejmują przydatną logikę analizowania. Na przykład InputDate<TValue> i InputNumber<TValue> obsługują nieparsowalne wartości sprawnie, rejestrując nieparsowalne wartości jako błędy walidacji. pl-PL: Typy, które mogą akceptować wartości null, obsługują również wartość null pola docelowego (na przykład int? dla liczby całkowitej, która dopuszcza wartość null).

Składnik InputNumber<TValue> obsługuje type="range" atrybut, który tworzy dane wejściowe zakresu, które obsługują powiązanie modelu i walidację formularza, zazwyczaj renderowane jako suwak lub kontrolka wybierania numerów, a nie pole tekstowe:

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

Aby uzyskać więcej informacji na temat składnika InputFile, zobacz również Przekazywanie plików w ASP.NET CoreBlazor.

Przykładowy formularz

Następujący Starship typ, który jest używany w kilku przykładach tego artykułu i przykładach w innych artykułach dotyczących węzłów formularzy , definiuje zróżnicowany zestaw właściwości z adnotacjami danych:

• Id jest wymagana, ponieważ jest oznaczona adnotacją za pomocą elementu RequiredAttribute. Id wymaga co najmniej jednego znaku, ale nie więcej niż 16 znaków przy użyciu znaku StringLengthAttribute.
• Description jest opcjonalny, ponieważ nie jest oznaczony elementem RequiredAttribute.
• Ciąg Classification jest wymagany.
• Właściwość MaximumAccommodation jest domyślnie równa zero, ale wymaga wartości z jednej do 100 000 na wartość RangeAttribute.
• IsValidatedDesign właściwość wymaga, aby właściwość miała wartość zgodną true z wybranym stanem, gdy właściwość jest powiązana z polem wyboru w interfejsie użytkownika (<input type="checkbox">).
• ProductionDate jest elementem DateTime i wymaganym.

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

Poniższy formularz akceptuje i weryfikuje dane wejściowe użytkownika przy użyciu:

• Właściwości i walidacja zdefiniowane w poprzednim Starship modelu.
• Kilka wbudowanych komponentów wejściowych Blazor.

Gdy właściwość modelu klasyfikacji statku (Classification) zostanie ustawiona, zaznaczana jest opcja zgodna z modelem. Na przykład checked="@(Model!.Classification == "Exploration")" w przypadku klasyfikacji statku poszukiwawczego. Przyczyną jawnego ustawienia zaznaczonej opcji jest to, że wartość <select> elementu jest obecna tylko w przeglądarce. Jeśli formularz jest renderowany na serwerze po przesłaniu, stan klienta jest zastępowany stanem z serwera, co zwykle nie oznacza, że opcja zostanie oznaczona jako wybrana. Ustawiając zaznaczoną opcję z właściwości modelu, klasyfikacja zawsze odzwierciedla stan modelu. Spowoduje to zachowanie wyboru klasyfikacji między przesyłaniem formularzy, które powodują rerendering formularza na serwerze. W sytuacjach, gdy formularz nie jest przerenderowany na serwerze, na przykład gdy tryb renderowania serwera interaktywnego zostaje bezpośrednio zastosowany do składnika, jawne przypisanie zaznaczonej opcji z modelu nie jest potrzebne, ponieważ Blazor zachowuje stan elementu <select> po stronie klienta.

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

Element EditForm w poprzednim przykładzie tworzy obiekt EditContext oparty na przypisanym Starship wystąpieniu (Model="...") i obsługuje prawidłowy formularz. W następnym przykładzie pokazano, jak przypisać element EditContext do formularza i zweryfikować, kiedy formularz zostanie przesłany.

W poniższym przykładzie:

• Używana jest skrócona wersja wcześniejszego Starfleet Starship Database formularza (Starship3 składnika), która akceptuje tylko wartość identyfikatora statku kosmicznego. Inne Starship właściwości otrzymują prawidłowe wartości domyślne po utworzeniu egzemplarza typu Starship.
• Metoda Submit jest wykonywana, gdy zostanie wybrany przycisk Submit.
• Formularz jest weryfikowany przez wywołanie metody EditContext.Validate w Submit.
• Rejestrowanie jest wykonywane w zależności od wyniku weryfikacji.

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

Uwaga

EditContext Zmiana po przypisaniu nie jest obsługiwana.

Wybór wielu opcji ze składnikiem InputSelect

Powiązanie obsługuje wybór opcji z komponentem multiple. Zdarzenie @onchange udostępnia tablicę wybranych opcji za pośrednictwem argumentów zdarzeń (ChangeEventArgs). Wartość musi być powiązana z typem tablicy, co powoduje, że InputSelect<TValue> automatycznie dodaje multiple atrybut do elementu <select> podczas renderowania składnika.

W poniższym przykładzie użytkownik musi wybrać co najmniej dwie klasyfikacje gwiazdek, ale nie więcej niż trzy klasyfikacje.

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

Aby uzyskać informacje na temat obsługi pustych ciągów i wartości null podczas wiązania danych, zobacz sekcję InputSelect.

Opcje powiązania InputSelect z wartościami obiektów null języka C#

Aby uzyskać informacje na temat obsługi pustych ciągów i wartości null w powiązaniu danych, zobacz ASP.NET Core Blazor powiązanie danych.

Obsługa nazw wyświetlanych

Kilka wbudowanych komponentów obsługuje nazwy wyświetlane z parametrem InputBase<TValue>.DisplayName .

W formularzu Starfleet Starship Database (Starship3 składnik) sekcji Przykładowy formularz data produkcji nowego statku kosmicznego nie ma określonej nazwy wyświetlanej:

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

Jeśli pole zawiera nieprawidłową datę przesłania formularza, komunikat o błędzie nie wyświetla przyjaznej nazwy. Nazwa pola "ProductionDate" nie zawiera spacji między znakami "Production" i "Date", gdy zostanie wyświetlona w podsumowaniu weryfikacji:

Pole ProductionDate musi być datą.

DisplayName Ustaw właściwość na przyjazną nazwę z spacją między wyrazami "Production" i "Date":

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

Podsumowanie weryfikacji wyświetla przyjazną nazwę, gdy wartość pola jest nieprawidłowa:

Pole Data Produkcji musi być datą.

Obsługa szablonu komunikatu o błędzie

InputDate<TValue> i InputNumber<TValue> wspierają szablony komunikatów o błędach.

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

W formularzu Starfleet Starship Database (Starship3 składnik) w sekcji Przykładowy formularz z przypisaną przyjazną nazwą wyświetlaną , pole Production Date generuje komunikat o błędzie przy użyciu następującego domyślnego szablonu komunikatu o błędzie:

The {0} field must be a date.

Pozycja symbolu zastępczego {0} to miejsce, w którym wartość właściwości DisplayName pojawia się, kiedy błąd zostanie wyświetlony użytkownikowi.

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

Pole Data Produkcji musi być datą.

Przypisz szablon niestandardowy do ParsingErrorMessage, aby zapewnić niestandardowy komunikat.

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

Pole Data produkcji ma nieprawidłową wartość daty.

InputHidden składnik do obsługi ukrytych pól wejściowych w formularzach

SkładnikInputHidden udostępnia ukryte pole wejściowe do przechowywania wartości ciągów.

W poniższym przykładzie dla właściwości formularza Parameter jest tworzone ukryte pole wejściowe. Po przesłaniu formularza zostanie wyświetlona wartość ukrytego pola:

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