ASP.NET Core Blazor 表單驗證

• 關於撰寫與設定基於模型的驗證規則，包括自訂與非同步規則、巢狀物件驗證及本地化，請參見 ASP.NET Core 中的驗證。
• 關於靜態伺服器端渲染（static SSR）中的即時瀏覽器驗證，請參見 ASP.NET Core Blazor 靜態 SSR 中的客戶端表單驗證。
• 欲了解完整的驗證器元件與遠端驗證實作，請參閱 ASP.NET Core Blazor 進階表單驗證。

• 關於撰寫與設定基於模型的驗證規則與巢狀物件驗證，請參見 ASP.NET Core 中的驗證。
• 欲了解完整的驗證器元件與遠端驗證實作，請參閱 ASP.NET Core Blazor 進階表單驗證。

• 欲了解完整的驗證器元件與遠端驗證實作，請參閱 ASP.NET Core Blazor 進階表單驗證。

對於靜態 SSR 表單貼文，指派一個唯一 FormName 並收到已發布的模型，格式為 [SupplyParameterFromForm]：

<EditForm Model="Model" FormName="starship" OnValidSubmit="Submit">
    ...
</EditForm>

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

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

如需更多關於在各種轉譯模式下的表單提交與模型繫結的資訊，請參閱 ASP.NET Core Blazor 表單概觀 和 ASP.NET Core Blazor 表單繫結。

靜態 SSR 表單可在靜態 SSR 中提供即時的瀏覽器回饋，並支援 ASP.NET Core Blazor 用戶端表單驗證。 表單發布後會在伺服器上再次權威驗證。

靜態的 SSR 表單會在伺服器上被驗證，且不會在請求間提供即時欄位驗證。

配置資料註解驗證

DataAnnotationsValidator 一律為表單啟用 DataAnnotations 驗證。 若要使用 Microsoft.Extensions.Validation 套件所提供的擴充驗證功能，請在 AddValidation 檔案中呼叫 Program 擴充方法：

builder.Services.AddValidation();

AddValidation 呼叫會註冊套件的驗證服務，並啟動原始碼產生器，為偵測到的模型類型建立驗證中繼資料。 可用的行為取決於該中繼資料是否包含表單模型：

在 .NET 10 中，這些 ValidatableTypeAttributeSkipValidationAttribute API 仍處於實驗階段。 欲了解詳情及可用變通方法，請參閱 ASP.NET Core 中的驗證。

使用 Microsoft.Extensions.Validation時，請以 C# 檔案（.cs）宣告模型類型，而非 Razor 元件檔案（.razor）。 原始碼產生器會從 C# 原始碼產生驗證元資料，且無法包含元件中 Razor 宣告的模型類型。

關於組態需求、驗證順序、自訂規則、巢狀物件圖及產生的元資料，請參見 ASP.NET Core 中的驗證。

驗證巢狀物件圖

在 .NET 9 或更早版本中，會DataAnnotationsValidator驗證頂層模型屬性，但不會遞迴驗證集合型或複雜型態屬性。 對於遞迴驗證，請使用實驗性 套件中的 和 ：

<EditForm Model="Model" OnValidSubmit="Submit">
    <ObjectGraphDataAnnotationsValidator />
    ...
</EditForm>

public class Starship
{
    [ValidateComplexType]
    public ShipDescription Description { get; set; } =
        new ShipDescription();
}

該套件在這些框架版本中仍處於實驗性質。

[CompareProperty] 屬性

對於 .NET 5 或更早版本，請使用 experimental 套件的 ComparePropertyAttribute，而非 CompareAttribute。 ComparePropertyAttribute 在欄位驗證和整份表單驗證期間，都會一致地將驗證結果與欄位關聯起來。

撰寫基於模型的自訂規則

當內建屬性無法表達規則時，請使用自訂 ValidationAttribute 或 IValidatableObject。 詳細指引請參閱 ASP.NET Core 中的驗證。

撰寫基於模型的自訂規則

當內建屬性無法表達規則時，請使用 自訂的驗證屬性 或實作 IValidatableObject。 兩者都貫穿 DataAnnotationsValidator。

從自訂屬性回傳 a ValidationResult 時，請包含已驗證的成員名稱，讓結果能顯示在該欄位的 ValidationMessage 元件中。

自訂屬性可透過 GetService 解析已註冊的服務。

靜態 SSR 不會在請求間提供即時的 .NET 欄位驗證。

若要進行非同步的整個表單驗證，請從 e.AddAsyncValidator 處理常式呼叫 OnValidationRequested。 若要以互動式形式進行非同步欄位驗證，請從OnFieldChanged處理器呼叫EditContext.RegisterAsyncFieldValidator。 同一欄位的新非同步驗證會取代並取消先前驗證。

關於基於模型的非同步驗證屬性，請參見 ASP.NET Core 中的驗證。 欲了解完整的可重複使用驗證器元件，請參見 ASP.NET Core Blazor 進階表單驗證。

非同步欄位驗證的輸入使用 pending 或 faulted，可選地使用 ， modified代替 valid 或 invalid ，且對應狀態適用。

要改變應用於輸入元件的類別，請從 推導出 FieldCssClassProvider。

using Microsoft.AspNetCore.Components.Forms;

public sealed class BootstrapFieldCssClassProvider : FieldCssClassProvider
{
    public override string GetFieldCssClass(
        EditContext editContext,
        in FieldIdentifier fieldIdentifier)
    {
        if (!editContext.IsModified(fieldIdentifier))
        {
            return string.Empty;
        }

        return editContext.IsValid(fieldIdentifier)
            ? "is-valid"
            : "is-invalid";
    }
}

using System.Linq;
using Microsoft.AspNetCore.Components.Forms;

public sealed class BootstrapFieldCssClassProvider : FieldCssClassProvider
{
    public override string GetFieldCssClass(
        EditContext editContext,
        in FieldIdentifier fieldIdentifier)
    {
        if (!editContext.IsModified(fieldIdentifier))
        {
            return string.Empty;
        }

        return editContext.GetValidationMessages(fieldIdentifier).Any()
            ? "is-invalid"
            : "is-valid";
    }
}

自訂系統 FieldCssClassProvider 會決定每個欄位的完整類別值。 若表單使用非同步欄位驗證，則在需要 pending 或 faulted 類別時，於提供者中處理 IsValidationPending(fieldIdentifier) 和 IsValidationFaulted(fieldIdentifier)。

將提供者指派至表單：EditContext

editContext.SetFieldCssClassProvider(
    new BootstrapFieldCssClassProvider());

若要自訂輸入標記，請呼叫 FieldCssClass 以取得目前提供者所選的類別。

當為 EditForm 指派模型時，其子內容會接收產生的 EditContext。 透過參數 Context 捕捉上下文，並呼叫 FieldCssClass 將欄位的類別套用到周圍的標記：

<EditForm Model="Model" Context="editContext">
    <DataAnnotationsValidator />

    <div class="@editContext.FieldCssClass(
        () => Model.Identifier)">
        <InputText @bind-Value="Model.Identifier" />
        <ValidationMessage For="() => Model.Identifier" />
    </div>
</EditForm>

用 IsValid(field) 來判斷欄位目前是否有驗證訊息。

對於欄位，可使用 !editContext.GetValidationMessages(field).Any() 檢查是否沒有訊息。

@{
    var identifier = editContext.Field(nameof(Starship.Identifier));
}

@if (editContext.IsModified(identifier) &&
    !editContext.IsValid(identifier))
{
    <p>Correct the identifier before continuing.</p>
}

@{
    var identifier = editContext.Field(nameof(Starship.Identifier));
}

@if (editContext.IsModified(identifier) &&
    editContext.GetValidationMessages(identifier).Any())
{
    <p>Correct the identifier before continuing.</p>
}

使用 IsValidationPending(field) 與 IsValidationFaulted(field) 用於非同步欄位驗證。 不含參數的方法描述表單層級的 ValidateAsync 傳遞，且不會彙總每個欄位的狀態。

這些狀態也包括由 DataAnnotationsValidator執行的非同步工作。 套用至屬性的 AsyncValidationAttribute 會在欄位驗證期間使用欄位狀態，包括預設的 pending 和 faulted CSS 類別。 在 ValidateAsync期間，非同步屬性 和 IAsyncValidatableObject 對無參數方法報告的形式層級狀態有貢獻。

待處理的即時指示器需要互動式渲染模式。 在靜態 SSR 表單發佈時，伺服器端驗證會在回應呈現前完成。

EditForm在呼叫 OnValidSubmit 或 OnInvalidSubmit之前使用ValidateAsync，因此等待同步與非同步驗證者。 處理 OnSubmit 時，請先呼叫 ValidateAsync，再處理表單：

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

@code {
    private async Task HandleSubmit(EditContext editContext)
    {
        if (await editContext.ValidateAsync())
        {
            await SaveAsync();
        }
    }
}

Validate同步方法在 .NET 11 中已過時。 它不會等待非同步驗證，且如果處理常式嘗試註冊非同步工作，便會擲回錯誤。

對於互動式表單，可使用表單層級的待處理狀態，在 ValidateAsync 執行期間停用提交功能：

<button type="submit" disabled="@editContext.IsValidationPending()">
    Save
</button>

處理 OnSubmit 時，請先呼叫 Validate，再處理表單：

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

@code {
    private void HandleSubmit(EditContext editContext)
    {
        if (editContext.Validate())
        {
            Save();
        }
    }
}

• ASP.NET Core 中的驗證

• ASP.NET Core Blazor 在靜態 SSR 中的客戶端表單驗證