syncfusion-blazor-dataform

实现 Syncfusion Blazor DataForm 组件

一份关于实现 Syncfusion Blazor DataForm 组件的全面指南。本指南涵盖 Blazor 应用中表单的安装、配置、数据绑定、验证、事件处理、模板和自定义。

组件概述

Syncfusion Blazor DataForm（SfDataForm）是一款功能强大的表单组件，可通过自动验证、字段绑定和事件处理，简化动态数据驱动表单的创建。它支持：

• 根据模型属性自动生成字段
• 内置验证，支持数据注释和自定义规则
• 多种绑定方式（模型、EditContext）
• 可自定义布局，支持列、分组和区块
• 基于模板的渲染，用于自定义字段设计
• 事件驱动架构，支持表单级和字段级响应
• 本地化支持，可本地化验证消息和 UI 文本
• 无障碍表单渲染，使用适当的标签和 ARIA 属性

文档和导航指南

入门

📄 阅读： references/getting-started.md

从这里开始，了解安装、NuGet 包设置、命名空间导入、服务注册、主题配置以及基本的 DataForm 示例。

• 安装和 NuGet 包
• Blazor 项目设置（Server/WebAssembly/Web App）
• 命名空间导入和服务注册
• 主题设置和配置
• 创建基本的 DataForm
• 运行你的第一个表单

表单项和字段配置

📄 阅读： references/form-items.md

了解如何定义表单项、配置标签、占位符、提示和编辑器类型，以及自定义单个字段的行为。

• FormItem 元素配置
• 标签和占位符配置
• 选择编辑器类型
• 禁用和隐藏字段
• 自定义属性（required、pattern、数据注释）
• 表单分组和列组织

自动生成表单字段

📄 阅读： references/autogeneration.md

了解如何使用 FormAutoGenerateItems 根据模型属性自动生成表单字段，包括类型映射，以及如何将自动生成的字段与自定义字段结合使用。

• FormAutoGenerateItems 概述
• 类型到组件的映射（int、string、DateTime、bool、enum 等）
• 为基元类型自动生成字段
• 结合自动生成的字段与自定义字段
• 取消特定字段的自动生成
• 配置选项

数据绑定

📄 阅读： references/data-binding.md

了解模型绑定、EditContext 绑定、双向数据绑定，以及如何绑定复杂数据结构。

• 模型绑定基础
• EditContext 绑定方式
• 表单级和字段级绑定
• 使用嵌套对象进行双向绑定
• 绑定复杂模型
• 数据初始化和默认值
• 表单名称和 ID 配置

表单验证

📄 阅读： references/validation.md

掌握如何使用数据注释、自定义验证规则、Fluent Validation 集成和错误消息显示来验证表单。

• 数据注释验证（Required、Range、EmailAddress 等）
• DataAnnotationsValidator 设置
• 自定义验证属性和规则
• Fluent Validation 框架集成
• 复杂模型验证场景
• 显示验证消息
• IsValid() 方法和验证状态
• 条件验证

表单和字段事件

📄 阅读： references/events.md

了解表单提交事件和字段级事件，以处理用户交互和表单状态变化。

• OnSubmit 事件（每次提交尝试时触发）
• OnValidSubmit 事件（仅在提交有效时触发）
• OnInvalidSubmit 事件（仅在验证失败时触发）
• OnUpdate 事件（字段值更改时触发）
• 事件参数和 EditContext 访问
• 异步事件处理程序
• 常见事件模式

布局自定义

📄 阅读： references/layout-customization.md

通过列、列跨度、标签位置、浮动标签和自定义按钮位置来自定义表单布局。

• 列布局配置
• 列跨度和行跨度
• 列数和响应式布局
• 标签位置（顶部、左侧、浮动）
• 浮动标签样式
• 按钮对齐和位置
• 自定义提交/重置按钮
• 使用 FormGroup 对表单分组

模板和自定义渲染

📄 阅读： references/templates.md

使用 FormTemplate 和 FormItemTemplate 以及渲染片段，创建自定义表单布局和字段渲染。

• 使用 FormTemplate 自定义整体表单布局
• 使用 FormItemTemplate 渲染单个字段
• 模板上下文和变量
• 自定义编辑器渲染
• 渲染片段和组合
• 高级模板模式
• 模板复用

本地化

📄 阅读： references/localization.md

为多种语言设置验证消息、表单标签和错误消息的本地化。

• 内置本地化资源
• 本地化错误消息
• 自定义本地化设置
• 区域性和语言配置
• RTL（从右到左）支持

快速入门示例

以下是一个可运行的最简示例，帮助你快速入门：

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

常见模式

模式 1：带验证和提交功能的表单

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

@code {
    private Contact contact = new();

    private async Task HandleValidSubmit(EditContext context)
    {
        // Save contact to database
        await SaveContactAsync(contact);
    }
}

模式 2：包含自定义字段的自动生成表单

<SfDataForm Model="@product">
    <FormItems>
        <FormItem Field="@nameof(product.Name)" LabelText="Product Name"></FormItem>
        <FormAutoGenerateItems></FormAutoGenerateItems>
        <FormItem Field="@nameof(product.Category)" EditorType="FormEditorType.DropDownList"></FormItem>
    </FormItems>
</SfDataForm>

@code {
    private Product product = new();
}

模式 3：包含级联字段的表单

<SfDataForm Model="@order" OnUpdate="HandleFieldUpdate">
    <FormItems>
        <FormItem Field="@nameof(order.Country)" LabelText="Country"></FormItem>
        <FormItem Field="@nameof(order.City)" LabelText="City"></FormItem>
        <FormAutoGenerateItems></FormAutoGenerateItems>
    </FormItems>
</SfDataForm>

@code {
    private Order order = new();

    private async Task HandleFieldUpdate(FormUpdateEventArgs args)
    {
        if (args.FieldName == nameof(Order.Country))
        {
            // Update cities based on selected country
            order.City = await GetCitiesForCountryAsync(order.Country);
        }
    }
}

模式 4：带列的自定义布局

<SfDataForm Model="@employee" ColumnCount="2">
    <FormItems>
        <FormItem Field="@nameof(employee.FirstName)" LabelText="First Name" ColumnSpan="1"></FormItem>
        <FormItem Field="@nameof(employee.LastName)" LabelText="Last Name" ColumnSpan="1"></FormItem>
        <FormItem Field="@nameof(employee.Email)" LabelText="Email" ColumnSpan="2"></FormItem>
        <FormItem Field="@nameof(employee.Department)" LabelText="Department" ColumnSpan="1"></FormItem>
        <FormItem Field="@nameof(employee.Salary)" LabelText="Salary" ColumnSpan="1"></FormItem>
    </FormItems>
</SfDataForm>

@code {
    private Employee employee = new();
}

关键属性和方法

常见属性

属性	类型	用途
Model	object	绑定到表单的数据模型
EditContext	EditContext	用于高级绑定场景的 Blazor EditContext
ColumnCount	int	表单布局的列数
OnValidSubmit	EventCallback	使用有效数据提交表单时触发
OnInvalidSubmit	EventCallback	使用无效数据提交表单时触发
OnSubmit	EventCallback	每次尝试提交表单时触发
OnUpdate	EventCallback	字段值更改时触发

可用的 FormEditorType 值

重要提示：大多数情况下，你无需指定 EditorType，因为 DataForm 会根据模型属性类型自动选择合适的编辑器。仅当需要覆盖默认行为时，才使用这些值。

FormEditorType	使用场景	何时使用
TextBox	单行文本输入	用于覆盖字符串字段的默认行为；数值类型无需指定
TextArea	多行文本输入	需要为字符串属性输入多行文本时
DatePicker	仅选择日期	用于覆盖 DateTime 的默认行为；DateTime 的默认编辑器
DateTimePicker	选择日期和时间	需要为 DateTime 属性同时选择日期和时间时
TimePicker	仅选择时间	需要为 TimeSpan 或 DateTime 仅选择时间时
DropDownList	从列表中选择下拉选项	用于枚举或自定义列表选择
ComboBox	可编辑且可筛选的下拉框	需要可搜索的下拉框时
AutoComplete	根据建议自动补全	需要自动建议功能时
Checkbox	布尔值切换（注意：'b' 为小写）	用于覆盖 bool 的默认行为；不是 CheckBox
Switch	布尔值切换开关	bool 属性的复选框替代项
Password	带遮蔽的密码输入	用于密码字符串字段

重要说明：

• ⚠️ 自动类型映射：DataForm 会智能地将 C# 类型自动映射到合适的编辑器：
  • int、long、decimal、double、float → 数值文本框（无需设置 EditorType）
  • string → 文本框（无需设置 EditorType）
  • bool → 复选框（无需设置 EditorType）
  • DateTime → 日期选择器（无需设置 EditorType）
  • enum → 下拉列表（无需设置 EditorType）
• ⚠️ 使用 Checkbox（'b' 为小写），不要使用 CheckBox（B 为大写）
• ⚠️ 不存在 NumericTextBox 编辑器类型；数值行为会根据属性类型自动设置
• ⚠️ 仅当需要覆盖默认行为时才指定 EditorType

常用方法

方法	用途
Refresh()	刷新表单并重新渲染字段
Submit()	以编程方式提交表单
Reset()	清空表单并重置为初始值
IsValid()	检查表单是否有效
Validate()	触发验证，但不提交

EditorType 重要指南

使用 EditorType 配置 FormItem 元素时，请牢记以下要点：

1. 自动选择编辑器：DataForm 会根据模型属性类型自动选择合适的编辑器。通常无需指定 EditorType，除非你想覆盖默认行为。

   • 数值属性（int、long、float、decimal、double）→ 自动渲染为数值文本框
   • 字符串属性 → 自动渲染为文本框
   • 布尔属性 → 自动渲染为复选框
   • DateTime 属性 → 自动渲染为日期选择器
   • 枚举属性 → 自动渲染为下拉框

2. 何时指定 EditorType：仅当需要覆盖默认行为时才指定 EditorType：

   • 多行字符串输入使用 FormEditorType.TextArea
   • 布尔值使用 FormEditorType.Switch 替代复选框
   • DateTime 需要包含时间时，使用 FormEditorType.DateTimePicker 替代 DatePicker
   • 密码字符串使用 FormEditorType.Password
   • 自定义列表使用 FormEditorType.DropDownList 或 ComboBox

3. Checkbox 大小写：显式指定复选框时，请使用 FormEditorType.Checkbox（'b' 为小写），不要使用 FormEditorType.CheckBox。

4. 不存在 NumericTextBox 类型：不存在 FormEditorType.NumericTextBox。数值行为会根据属性类型自动设置。

示例：

<FormItem Field="@nameof(model.Quantity)" 
          LabelText="Quantity">
</FormItem>


<FormItem Field="@nameof(model.IsActive)" 
          LabelText="Is Active">
</FormItem>


<FormItem Field="@nameof(model.Description)" 
          LabelText="Description"
          EditorType="FormEditorType.TextArea">
</FormItem>


<FormItem Field="@nameof(model.IsEnabled)" 
          LabelText="Enabled"
          EditorType="FormEditorType.Switch">
</FormItem>

相关技能

• Syncfusion Blazor Components - 所有 Blazor 组件的主要库技能
• AutoComplete - 用于下拉字段编辑器
• File Upload - 用于文件输入字段