ASP.NET 核心 Blazor 輸入元件

本文說明 Blazor的內建輸入元件。

輸入元件

架構 Blazor 提供內建的輸入元件來接收和驗證用戶輸入。 下表中的內建輸入元件在EditForm中，當與EditContext一起使用時將受到支援。

表格中的元件在表單外的 Razor 元件標記中也受支援。 輸入會在變更時以及提交表單時進行驗證。

輸入元件	轉譯為...
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>	兒童組 InputRadio<TValue>
InputSelect<TValue>	<select>
InputText	<input>
InputTextArea	<textarea>

如需元件的詳細資訊 InputFile ，請參閱 ASP.NET 核心 Blazor 檔案上傳。

所有輸入元件，包括 EditForm支援任意屬性。 任何不符合元件參數的屬性，會新增至轉譯的 HTML 元素。

輸入元件提供在欄位變更時驗證的預設行為：

• 對於具有 EditContext的表單中的輸入元件，預設的驗證行為包括更新欄位 CSS 類別，以反映欄位的狀態為有效或無效，以及基礎 HTML 元素的驗證樣式。
• 對於沒有 EditContext的控件，預設驗證會反映有效或無效的狀態，但不會提供基礎 HTML 元素的驗證樣式。

某些元件包含實用的剖析邏輯。 例如，InputDate<TValue> 和 InputNumber<TValue> 透過將無法剖析的值登記為驗證錯誤，妥善處理無法剖析的值。 可以接受空值的類型也支援目標欄位的可空性（例如對於可為空的整數使用int?）。

元件 InputNumber<TValue> 支援 type="range" 屬性，其會建立支援模型繫結和表單驗證的範圍輸入，通常會轉譯為滑桿或撥號控制項，而不是文本框：

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

如需元件的詳細資訊 InputFile ，請參閱 ASP.NET 核心 Blazor 檔案上傳。

範例表單

下列 Starship 類型會用於本文的數個範例，以及其他 Forms 節點文章中的範例，使用數據批注來定義一組不同的屬性：

• Id 是必須的，因為它有 RequiredAttribute 的註解。 Id 的值需使用 StringLengthAttribute，其字元數至少為一個且不超過 16 個字元。
• Description 是選擇性的，因為它未加上 RequiredAttribute批注。
• Classification 是必要的。
• 屬性 MaximumAccommodation 預設為零，但每個 屬性 RangeAttribute需要一到 100,000 的值。
• IsValidatedDesign 要求屬性具有 true 值，當屬性系結至UI中的<input type="checkbox">複選框時，該值會符合選取的狀態。
• ProductionDate DateTime是必須的。

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

下列表單使用 來接受及驗證使用者輸入：

• 在上述 Starship 模型中定義的屬性和驗證。
• 數個 Blazor的內建輸入元件。

當設定船舶分類的模型屬性時，符合模型的選項會被勾選。 例如， checked="@(Model!.Classification == "Exploration")" 用於探勘船的分類。 明確設定核取選項的原因是元素的值 <select> 只存在於瀏覽器中。 如果表單在提交後在伺服器上呈現，用戶端的任何狀態將被伺服器的狀態覆蓋，這通常不會顯示選項為已勾選。 透過設定模型屬性的選取選項，分類將始終反映模型的狀態。 這會保留跨表單提交的分類選取選項，導致伺服器上的表單重新呈現。 如果窗體未在伺服器上重新呈現，例如當互動式伺服器渲染模式直接套用至元件時，不需要從模型明確指派已選取的選項。因為 Blazor 會在用戶端保留 <select> 元素的狀態。

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 會根據指派的 EditContext 實例 (Starship) 建立 Model="..."，並處理有效的表單。 下一個範例示範如何將 指派 EditContext 給窗體，並在提交窗體時進行驗證。

在以下範例中：

• 使用早期Starfleet Starship Database表單（Starship3元件）的縮短版本，只接受星際飛船標識碼的值。當建立類型的實例Starship時，其他Starship屬性會收到有效的預設值。
• 當 Submit 按鈕被選取時，方法 Submit 將執行。
• 表單透過在EditContext.Validate方法中呼叫Submit進行驗證。
• 根據驗證結果進行日誌記錄。

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

備註

指派後不支援變更 EditContext 。

使用 InputSelect 元件選取多個選項

綁定支持使用 multiple 元件進行 InputSelect<TValue> 選項選擇。 事件 @onchange 會透過 事件自變數 （ChangeEventArgs） 提供所選取選項的陣列。 值必須被綁定為陣列型態，這會在轉譯時導致InputSelect<TValue>元件自動將 multiple 屬性新增至<select>元素。

在下列範例中，用戶必須至少選取兩個星際飛船分類，但不超過三個分類。

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

如需數據系結中如何處理空字串和null值的資訊，請參閱InputSelect將選項系結至 C# 物件null值一節。

將選項系結 InputSelect 至 C# 物件 null 值

如需如何在數據系結中處理空字串和null值的資訊，請參閱核心數據系結 ASP.NETBlazor。

顯示名稱支援

數個內建元件支援使用 InputBase<TValue>.DisplayName 參數顯示名稱。

在Starfleet Starship DatabaseStarship3區段的表單（元件）中，新星艦的生產日期未指定顯示名稱：

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

如果欄位在送出表單時包含無效的日期，則錯誤信息不會顯示易於理解的名稱。 域名稱 「ProductionDate在驗證摘要中出現時，在 」Production「 和 」Date之間沒有空格：

ProductionDate 欄位必須是日期。

將 DisplayName 屬性設定為易記名稱，並在 「Production」 和 「Date兩個字之間加上空格：

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

當欄位的值無效時，驗證摘要會顯示易記名稱：

[生產日期] 欄位必須是日期。

錯誤訊息範本支援

InputDate<TValue> 與 InputNumber<TValue> 支援錯誤訊息樣本：

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

在 Starfleet Starship Database 表單（Starship3 元件）所在的 範例表單 區段中，已指派 易記顯示名稱，Production Date 欄位將使用以下預設錯誤訊息範本產生錯誤訊息：

The {0} field must be a date.

佔位元的位置 {0} 是當錯誤顯示給使用者時，屬性的值 DisplayName 會出現的位置。

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

[生產日期] 欄位必須是日期。

將自訂範本指派給 ParsingErrorMessage ，以提供自訂訊息：

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

[生產日期] 欄位的日期值不正確。