ASP.NET Core Blazor 表單繫結

本文說明如何在 Blazor 表單中使用繫結。

EditForm/EditContext 模型

EditForm 會根據指派的物件建立 EditContext，做為表單中其他元件的串聯值。 EditContext 會追蹤有關編輯程序的中繼資料，包括哪些表單欄位已修改和目前的驗證訊息。 指派給 EditForm.Model 或 EditForm.EditContext 可以將表單繫結至資料。

模型繫結

指派給 EditForm.Model：

<EditForm ... Model="Model" ...>
    ...
</EditForm>

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

    protected override void OnInitialized() => Model ??= new();
}

內容繫結

指派給 EditForm.EditContext：

<EditForm ... EditContext="editContext" ...>
    ...
</EditForm>

@code {
    private EditContext? editContext;

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

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

將 EditContext或Model之一指派給 EditForm。 如果同時指派兩者，則會擲出執行階段錯誤。

支援的類型

繫結支援：

• 基本類型
• 集合
• 複雜類型
• 遞迴型別
• 具有建構函式的型別
• 列舉

您也可以使用 [DataMember] 和 [IgnoreDataMember] 屬性來自訂模型繫結。 使用這些屬性來重新命名屬性、忽略屬性，以及視需要標記屬性。

其他繫結選項

呼叫 AddRazorComponents 時，可從 RazorComponentsServiceOptions 取得其他模型繫結選項：

• MaxFormMappingCollectionSize：表單集合中允許的元素數目上限。
• MaxFormMappingRecursionDepth：遞迴對應表單資料時允許的最大深度。
• MaxFormMappingErrorCount：對應表單資料時允許的錯誤數目上限。
• MaxFormMappingKeySize：用來讀取表單資料索引鍵的緩衝區大小上限。

以下示範架構指派的預設值：

builder.Services.AddRazorComponents(options =>
{
    options.FormMappingUseCurrentCulture = true;
    options.MaxFormMappingCollectionSize = 1024;
    options.MaxFormMappingErrorCount = 200;
    options.MaxFormMappingKeySize = 1024 * 2;
    options.MaxFormMappingRecursionDepth = 64;
}).AddInteractiveServerComponents();

表單名稱

使用 FormName 參數來指派表單名稱。 表單名稱必須是唯一的，才能繫結模型資料。 下列表單名為 RomulanAle：

<EditForm ... FormName="RomulanAle" ...>
    ...
</EditForm>

提供表單名稱：

• 所有由靜態轉譯的伺服器端元件提交的表單都需要。
• 對於以互動方式轉譯的元件所提交的表單並非必要，其中包括 Blazor WebAssembly 應用程式中的表單和具有互動式轉譯模式的元件。 不過，我們建議為每個表單提供唯一的表單名稱，以避免在表單的互動功能遭到捨棄時發生執行階段表單張貼錯誤。

只有在表單以傳統 HTTP POST 要求的形式 (來自靜態轉譯的伺服器端元件) 張貼到端點時，才會檢查表單名稱。 架構不會在轉譯表單時擲出例外狀況，而是只會在 HTTP POST 到達且未指定表單名稱時擲出例外狀況。

依預設，應用程式的根元件上方有一個未命名的 (空字串) 表單範圍，當應用程式中沒有表單名稱衝突時，此範圍就已足夠。 若有可能發生表單名稱衝突，(例如，若您納入某個程式庫中的表單，但無權控制程式庫開發人員所使用的表單名稱)，請為 Blazor Web 應用程式主要專案中的 FormMappingScope 元件提供表單名稱範圍。

在下列範例中，HelloFormFromLibrary 元件具有名為 Hello 的表單，且位於程式庫中。

HelloFormFromLibrary.razor：

<EditForm FormName="Hello" Model="this" OnSubmit="Submit">
    <InputText @bind-Value="Name" />
    <button type="submit">Submit</button>
</EditForm>

@if (submitted)
{
    <p>Hello @Name from the library's form!</p>
}

@code {
    bool submitted = false;

    [SupplyParameterFromForm]
    public string? Name { get; set; }

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

下列 NamedFormsWithScope 元件會使用程式庫的 HelloFormFromLibrary 元件，而且也有名為 Hello 的表單。 對於 HelloFormFromLibrary 元件所提供的任何表單，FormMappingScope 元件的範圍名稱皆為 ParentContext。 雖然此範例中的兩個表單都有表單名稱 (Hello)，但這些表單名稱並未衝突，且事件會路由至表單 POST 事件的正確表單。

NamedFormsWithScope.razor：

@page "/named-forms-with-scope"

<div>Hello form from a library</div>

<FormMappingScope Name="ParentContext">
    <HelloFormFromLibrary />
</FormMappingScope>

<div>Hello form using the same form name</div>

<EditForm FormName="Hello" Model="this" OnSubmit="Submit">
    <InputText @bind-Value="Name" />
    <button type="submit">Submit</button>
</EditForm>

@if (submitted)
{
    <p>Hello @Name from the app form!</p>
}

@code {
    bool submitted = false;

    [SupplyParameterFromForm]
    public string? Name { get; set; }

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

從表單提供參數 ([SupplyParameterFromForm])

[SupplyParameterFromForm] 屬性會指出應該從表單的表單資料提供相關聯屬性的值。 要求中符合屬性名稱的資料會繫結至屬性。 根據 InputBase<TValue> 的輸入會產生符合 Blazor 用於模型繫結名稱的表單值名稱。

您可以將下列表單繫結參數指定給 [SupplyParameterFromForm] 屬性：

• Name：取得或設定參數的名稱。 該名稱會用來判斷要用來比對表單資料的前置詞，以及決定是否需要繫結值。
• FormName：取得或設定處理常式的名稱。 該名稱會用來依表單名稱比對表單的參數，以決定是否需要繫結值。

下列範例會依表單名稱，將兩個表單獨立繫結至其模型。

Starship6.razor：

@page "/starship-6"
@inject ILogger<Starship6> Logger

<EditForm Model="Model1" OnSubmit="Submit1" FormName="Holodeck1">
    <div>
        <label>
            Holodeck 1 Identifier: 
            <InputText @bind-Value="Model1!.Id" />
        </label>
    </div>
    <div>
        <button type="submit">Submit</button>
    </div>
</EditForm>

<EditForm Model="Model2" OnSubmit="Submit2" FormName="Holodeck2">
    <div>
        <label>
            Holodeck 2 Identifier: 
            <InputText @bind-Value="Model2!.Id" />
        </label>
    </div>
    <div>
        <button type="submit">Submit</button>
    </div>
</EditForm>

@code {
    [SupplyParameterFromForm(FormName = "Holodeck1")]
    public Holodeck? Model1 { get; set; }

    [SupplyParameterFromForm(FormName = "Holodeck2")]
    public Holodeck? Model2 { get; set; }

    protected override void OnInitialized()
    {
        Model1 ??= new();
        Model2 ??= new();
    }

    private void Submit1()
    {
        Logger.LogInformation("Submit1: Id = {Id}", Model1?.Id);
    }

    private void Submit2()
    {
        Logger.LogInformation("Submit2: Id = {Id}", Model2?.Id);
    }

    public class Holodeck
    {
        public string? Id { get; set; }
    }
}

巢狀和繫結表單

下列指導示範如何為子表單建立巢狀和繫結。

下列飛船詳細資料類別 (ShipDetails) 會保存子表單的描述和長度。

ShipDetails.cs：

namespace BlazorSample;

public class ShipDetails
{
    public string? Description { get; set; }
    public int? Length { get; set; }
}

下列 Ship 類別會命名識別碼 (Id)，並包含飛船詳細資料。

Ship.cs：

namespace BlazorSample
{
    public class Ship
    {
        public string? Id { get; set; }
        public ShipDetails Details { get; set; } = new();
    }
}

下列子表單用於編輯 ShipDetails 型別的值。 這是藉由在元件頂端繼承 Editor<T> 來實作。 Editor<T> 可確保子元件會根據模型產生正確的表單欄位名稱 (T)，其中 T 在下列範例中為 ShipDetails。

StarshipSubform.razor：

@inherits Editor<ShipDetails>

<div>
    <label>
        Description: 
        <InputText @bind-Value="Value!.Description" />
    </label>
</div>
<div>
    <label>
        Length: 
        <InputNumber @bind-Value="Value!.Length" />
    </label>
</div>

主要表單會繫結至 Ship 類別。 StarshipSubform 元件會用來編輯飛船詳細資料，繫結為 Model!.Details。

Starship7.razor：

@page "/starship-7"
@inject ILogger<Starship7> Logger

<EditForm Model="Model" OnSubmit="Submit" FormName="Starship7">
    <div>
        <label>
            Identifier: 
            <InputText @bind-Value="Model!.Id" />
        </label>
    </div>
    <StarshipSubform @bind-Value="Model!.Details" />
    <div>
        <button type="submit">Submit</button>
    </div>
</EditForm>

@code {
    [SupplyParameterFromForm]
    public Ship? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private void Submit()
    {
        Logger.LogInformation("Id = {Id} Desc = {Description} Length = {Length}",
            Model?.Id, Model?.Details?.Description, Model?.Details?.Length);
    }
}

進階表單對應錯誤案例

架構會具現化並填入表單的 FormMappingContext，這是與指定表單對應作業相關聯的內容。 每個對應範圍 (由 FormMappingScope 元件定義) 都會具現化 FormMappingContext。 每次 [SupplyParameterFromForm] 向內容要求值時，架構都會以嘗試的值和任何對應錯誤填入 FormMappingContext。

開發人員預期不會直接與 FormMappingContext 互動，因為它主要是 InputBase<TValue>、EditContext 和其他內部實作的資料來源，以將對應錯誤顯示為驗證錯誤。 在進階自訂案例中，開發人員可以以 [CascadingParameter] 的形式直接存取 FormMappingContext，以便撰寫會取用嘗試的值和對應錯誤的自訂程式碼。

選項按鈕

本節中的範例是以本文範例表單小節的 Starfleet Starship Database 表單 (Starship3 元件) 為基礎。

將下列 enum 型別新增至應用程式。 建立新的檔案來保存它們，或將它們新增至 Starship.cs 檔案。

public class ComponentEnums
{
    public enum Manufacturer { SpaceX, NASA, ULA, VirginGalactic, Unknown }
    public enum Color { ImperialRed, SpacecruiserGreen, StarshipBlue, VoyagerOrange }
    public enum Engine { Ion, Plasma, Fusion, Warp }
}

讓 enums 類別可供存取：

• Starship.cs 中的 Starship 模型 (例如，using static ComponentEnums;)。
• Starfleet Starship Database 表單 (Starship3.razor) (例如，@using static ComponentEnums)。

使用 InputRadio<TValue> 元件搭配 InputRadioGroup<TValue> 元件來建立選項按鈕群組。 在下列範例中，屬性會新增至輸入元件一文中的範例表單小節所說明的 Starship 模型：

[Required]
[Range(typeof(Manufacturer), nameof(Manufacturer.SpaceX), 
    nameof(Manufacturer.VirginGalactic), ErrorMessage = "Pick a manufacturer.")]
public Manufacturer Manufacturer { get; set; } = Manufacturer.Unknown;

[Required, EnumDataType(typeof(Color))]
public Color? Color { get; set; } = null;

[Required, EnumDataType(typeof(Engine))]
public Engine? Engine { get; set; } = null;

更新輸入元件一文中範例表單小節的 Starfleet Starship Database 表單 (Starship3 元件)。 新增要產生的元件：

• 飛船製造商的選項按鈕群組。
• 引擎和飛船色彩的巢狀選項按鈕群組。

注意

巢狀選項按鈕群組不常用於表單，因為它們可能會導致表單控制項的配置錯亂，進而可能混淆使用者。 不過，在某些情況下它們在 UI 設計中有意義，例如會配對兩個使用者輸入、飛船引擎和飛船色彩建議的下列範例。 表單驗證需要一個引擎和一種色彩。 表單的配置會使用巢狀 InputRadioGroup<TValue> 來配對引擎和色彩建議。 不過，使用者可以結合任何引擎與任何色彩來提交表單。

注意

針對下列範例，務必將 ComponentEnums 類別提供給元件：

@using static ComponentEnums

<fieldset>
    <legend>Manufacturer</legend>
    <InputRadioGroup @bind-Value="Model!.Manufacturer">
        @foreach (var manufacturer in Enum.GetValues<Manufacturer>())
        {
            <div>
                <label>
                    <InputRadio Value="manufacturer" />
                    @manufacturer
                </label>
            </div>
        }
    </InputRadioGroup>
</fieldset>

<fieldset>
    <legend>Engine and Color</legend>
    <p>
        Engine and color pairs are recommended, but any
        combination of engine and color is allowed.
    </p>
    <InputRadioGroup Name="engine" @bind-Value="Model!.Engine">
        <InputRadioGroup Name="color" @bind-Value="Model!.Color">
            <div style="margin-bottom:5px">
                <div>
                    <label>
                        <InputRadio Name="engine" Value="Engine.Ion" />
                        Ion
                    </label>
                </div>
                <div>
                    <label>
                        <InputRadio Name="color" Value="Color.ImperialRed" />
                        Imperial Red
                    </label>
                </div>
            </div>
            <div style="margin-bottom:5px">
                <div>
                    <label>
                        <InputRadio Name="engine" Value="Engine.Plasma" />
                        Plasma
                    </label>
                </div>
                <div>
                    <label>
                        <InputRadio Name="color" Value="Color.SpacecruiserGreen" />
                        Spacecruiser Green
                    </label>
                </div>
            </div>
            <div style="margin-bottom:5px">
                <div>
                    <label>
                        <InputRadio Name="engine" Value="Engine.Fusion" />
                        Fusion
                    </label>
                </div>
                <div>
                    <label>
                        <InputRadio Name="color" Value="Color.StarshipBlue" />
                        Starship Blue
                    </label>
                </div>
            </div>
            <div style="margin-bottom:5px">
                <div>
                    <label>
                        <InputRadio Name="engine" Value="Engine.Warp" />
                        Warp
                    </label>
                </div>
                <div>
                    <label>
                        <InputRadio Name="color" Value="Color.VoyagerOrange" />
                        Voyager Orange
                    </label>
                </div>
            </div>
        </InputRadioGroup>
    </InputRadioGroup>
</fieldset>

注意

如果省略 Name，InputRadio<TValue> 元件會依其最新的上階分組。

如果您在輸入元件一文的範例表單小節的 Starship3 元件中實作上述 Razor 標記，請更新 Submit 方法的記錄：

Logger.LogInformation("Id = {Id} Description = {Description} " +
    "Classification = {Classification} MaximumAccommodation = " +
    "{MaximumAccommodation} IsValidatedDesign = " +
    "{IsValidatedDesign} ProductionDate = {ProductionDate} " +
    "Manufacturer = {Manufacturer}, Engine = {Engine}, " +
    "Color = {Color}",
    Model?.Id, Model?.Description, Model?.Classification,
    Model?.MaximumAccommodation, Model?.IsValidatedDesign,
    Model?.ProductionDate, Model?.Manufacturer, Model?.Engine, 
    Model?.Color);