syncfusion-blazor-dataform

用途

Syncfusion Blazor DataForm（组件名 SfDataForm）用于在 Blazor 应用中创建动态、数据绑定的表单，自动完成字段生成、验证与事件处理，减少手写表单结构的工作量。适用于 Blazor Server、WebAssembly 与 Web App 项目。

主要能力

从模型属性自动生成字段，支持类型到组件的映射（int、string、DateTime、bool、enum 等），并可将自动生成字段与自定义字段组合使用。
内置验证：支持数据注解（Required、Range、EmailAddress 等）、DataAnnotationsValidator、自定义验证特性与规则、Fluent Validation 集成，以及验证消息显示与 IsValid() 状态判断。
数据绑定：支持模型绑定、EditContext 绑定、表单级与字段级绑定、双向绑定与嵌套对象、复杂模型绑定。
布局定制：列数、列跨度与行跨度、响应式、标签位置（顶部、左侧、浮动标签）、按钮对齐与自定义提交/重置按钮、FormGroup 分组。
模板：FormTemplate 用于整体布局定制，FormItemTemplate 用于单个字段渲染，支持 render fragments 与模板复用。
事件：OnSubmit（每次提交尝试触发）、OnValidSubmit（验证通过时触发）、OnInvalidSubmit（验证失败时触发）、OnUpdate（字段值变化时触发），支持异步处理。
本地化：验证消息、标签与错误消息的多语言支持，含内置资源、自定义本地化、文化语言配置与 RTL 支持。

使用方式

安装与配置：参见 getting-started 部分，涵盖 NuGet 包安装、命名空间导入、服务注册、主题配置与基础示例。

最小示例：

@page "/dataform-example"
@using System.ComponentModel.DataAnnotations
@using Syncfusion.Blazor.DataForm

<SfDataForm ID="MyDataForm"
            Model="@employeeModel">
    <FormValidator>
        <DataAnnotationsValidator></DataAnnotationsValidator>
    </FormValidator>
    <FormItems>
        <FormAutoGenerateItems></FormAutoGenerateItems>
    </FormItems>
</SfDataForm>

@code {
    public class EmployeeModel
    {
        [Required(ErrorMessage = "First Name is required")]
        [Display(Name = "First Name")]
        public string FirstName { get; set; }

        [Required(ErrorMessage = "Email is required")]
        [EmailAddress(ErrorMessage = "Invalid email address")]
        [Display(Name = "Email")]
        public string Email { get; set; }

        [Range(18, 65, ErrorMessage = "Age must be between 18 and 65")]
        [Display(Name = "Age")]
        public int Age { get; set; }

        [Display(Name = "Date of Birth")]
        public DateTime? DateOfBirth { get; set; }
    }

    private EmployeeModel employeeModel = new EmployeeModel();
}

常用属性：Model（绑定数据模型）、EditContext（高级绑定场景）、ColumnCount（列布局）、OnValidSubmit、OnInvalidSubmit、OnSubmit、OnUpdate。

常用方法：Refresh()（刷新并重新渲染字段）、Submit()（程序化提交）、Reset()（重置为初始值）、IsValid()（检查有效性）、Validate()（不提交而触发验证）。

常用模式：

模式一：带验证与提交的表单，使用 OnValidSubmit 处理有效提交。

<SfDataForm ID="ContactForm" Model="@contact" OnValidSubmit="HandleValidSubmit">
    <FormValidator>
        <DataAnnotationsValidator></DataAnnotationsValidator>
    </FormValidator>
    <FormItems>
        <FormItem Field="@nameof(contact.Name)" LabelText="Full Name"></FormItem>
        <FormItem Field="@nameof(contact.Email)" LabelText="Email Address"></FormItem>
        <FormItem Field="@nameof(contact.Message)" EditorType="FormEditorType.TextArea"></FormItem>
    </FormItems>
</SfDataForm>

模式二：自动生成字段与自定义字段混用。

模式三：级联字段，通过 OnUpdate 监听字段变化，例如根据所选国家更新城市。

模式四：多列布局，通过 ColumnCount 与 ColumnSpan 控制。

EditorType 说明

多数情况下无需指定 EditorType，组件会按属性类型自动选择编辑器：

int、long、decimal、double、float → 数字文本框
string → 文本框
bool → 复选框
DateTime → 日期选择器
enum → 下拉列表

仅在需要覆盖默认行为时指定 EditorType，例如：

FormEditorType.TextArea 用于多行字符串
FormEditorType.Switch 替代复选框表示布尔值
FormEditorType.DateTimePicker 用于需要时间的 DateTime
FormEditorType.Password 用于密码字符串
FormEditorType.DropDownList 或 ComboBox 用于自定义列表

其他可用的 FormEditorType：TextBox、DatePicker、TimePicker、AutoComplete、Checkbox。

重要注意事项：

复选框必须写为 FormEditorType.Checkbox（小写 b），不是 CheckBox。
不存在 FormEditorType.NumericTextBox，数字行为由属性类型自动决定。
仅在需要覆盖默认行为时指定 EditorType。

适用场景

需要在 Blazor 应用中快速实现数据驱动、带验证的表单；希望从模型自动生成字段以减少手写代码；需要自定义字段布局、模板、分组与多列排布；需要表单与字段级事件响应用户交互；需要多语言与 RTL 支持的表单界面。

限制与缺失信息

关于该组件的具体收费、价格、授权方式、性能表现或与其他版本的兼容性细节，资料未提供，暂未提供。