syncfusion-maui-dataform

实现 .NET MAUI DataForm（SfDataForm）

Syncfusion .NET MAUI DataForm（SfDataForm）是一款全面的表单构建控件，可根据数据对象自动生成数据录入表单。它提供内置编辑器、验证、灵活布局和丰富的自定义选项，可用于创建专业的数据收集和编辑界面。

何时使用此技能

在以下情况下使用此技能：

• 创建数据录入表单（登录、注册、联系人、员工表单等）
• 编辑数据对象，根据模型类自动生成表单
• 验证用户输入，使用内置或自定义验证规则
• 自定义表单编辑器（文本、数值、日期、下拉列表等）
• 布局表单，采用线性或网格排列方式
• 对表单字段分组，并使用可折叠区段
• 本地化表单，支持多种语言
• 支持 RTL 布局，用于从右向左书写的语言
• 实现浮动标签设计，适用于现代 UI
• 处理表单提交，支持不同模式（LostFocus、PropertyChanged、Manual）

典型场景：

• 用户注册和个人资料编辑
• 业务数据录入（订单、发票、联系人）
• 设置和配置界面
• 调查和问卷表单
• 搜索和筛选表单

组件概述

主要功能：

• 自动生成： 根据数据对象属性自动创建表单编辑器
• 10+ 种内置编辑器： 文本、数值、日期、时间、下拉列表、复选框、开关、掩码输入等
• 验证： 内置支持数据注解和自定义验证
• 灵活布局： 支持分组的线性或网格布局
• 自定义： 自定义编辑器、样式和行为修改
• 本地化： 通过资源文件支持多种语言
• 无障碍访问： 支持 RTL 和屏幕阅读器兼容性

文档与导航指南

入门

📄 阅读： references/getting-started.md

了解设置和使用 DataForm 的基础知识：

• 在 Visual Studio、VS Code 和 Rider 中安装 NuGet 包
• 在 MauiProgram.cs 中注册处理程序
• 创建数据对象和视图模型
• 绑定 DataObject 属性
• 实现第一个 DataForm
• 在 StackLayout 容器中设置 DataForm 大小
• 基本配置和设置

何时阅读： 开始使用 DataForm 的新项目，或需要安装指南时。

---

内置编辑器

📄 阅读： references/built-in-editors.md

了解 10+ 种内置编辑器类型及其自动生成方式：

• 文本编辑器（Text、Multiline、Password）
• 数值编辑器（SfNumericEntry）
• 日期和时间编辑器（DatePicker、TimePicker）
• 布尔值编辑器（CheckBox、Switch）
• 选择编辑器（Picker、ComboBox、AutoComplete、RadioGroup）
• 用于电话号码和信用卡号的 MaskedText 编辑器
• 基于数据类型的编辑器生成规则
• DataFormItem 类型和输入控件映射
• 用于选择编辑器的 DataType 特性

何时阅读： 需要了解每种属性类型会生成哪种编辑器，或查看可用的编辑器选项时。

---

自定义编辑器

📄 阅读： references/custom-editors.md

了解如何配置和创建自定义编辑器：

• 显式配置编辑器（切换编辑器类型）
• 更改属性的编辑器类型
• 实现自定义编辑器视图
• 自定义 ItemManager
• 重写 InitializeDataEditor 方法
• 集成自定义控件
• 编辑器属性映射和绑定
• 高级编辑器自定义场景

何时阅读： 需要更改某个属性的默认编辑器，或实现完全自定义的编辑器控件时。

---

验证

📄 阅读： references/validation.md

实现全面的数据验证：

• 内置验证特性（Required、StringLength、Range、EmailAddress 等）
• 数据注解验证
• 验证模式（LostFocus、PropertyChanged、Manual）
• 用于日期验证的 DataFormDateRange 特性
• 自定义验证逻辑的实现
• 验证错误的显示和样式设置
• 使用 Validate() 方法进行编程式验证
• ValidationLabel 自定义
• 实时验证与提交时验证

阅读时机： 需要验证表单输入、显示错误消息或实现自定义验证规则时。

---

数据注解

📄 阅读： references/data-annotations.md

使用特性声明式配置 DataForm 行为：

• Display 特性（Name、Prompt、GroupName、AutoGenerateField）
• 用于字段排序的 Order 特性
• 格式化特性（DisplayFormat）
• ReadOnly 和 Editable 特性
• 用于选择编辑器类型的 DataType 特性
• 可见性控制特性
• 自定义特性的实现
• 特性组合与优先级规则

阅读时机： 想要使用模型属性上的特性配置 DataForm，或需要控制字段生成时。

---

布局

📄 阅读： references/layout.md

使用灵活的布局选项组织表单字段：

• 线性布局（每行一个字段，默认）
• 使用 ColumnCount 属性的网格布局
• 标签位置（Left、Top）
• 用于自定义列顺序的 ItemsOrderInRow
• 行列跨度配置
• 布局自定义技巧
• 响应式布局策略
• 单独配置各组布局

阅读时机： 需要将表单字段排列为多列，或自定义表单布局结构时。

---

分组

📄 阅读： references/grouping.md

将相关表单字段分组：

• 用于字段分组的 GroupName 特性
• 组标题自定义
• 可折叠／展开的分组
• 单独配置各组布局（线性或网格）
• 分组排序和外观
• 用于动态分组的 GenerateDataFormItem 事件
• 嵌套分组策略

阅读时机： 需要将表单字段组织成逻辑分区或可折叠分组时。

---

DataForm 设置

📄 阅读： references/dataform-settings.md

配置 DataForm 的全局属性和外观：

• AutoGenerateItems 属性（自动或手动生成）
• 用于手动创建项的 Items 集合
• 标签设置（宽度、位置、样式）
• 编辑器高度和间距配置
• 内边距和外边距属性
• 背景和视觉外观
• 用于控制全局行为的 ItemManager 自定义
• 主题集成

阅读时机： 需要自定义 DataForm 控件的整体外观或行为时。

---

编辑行为

📄 阅读： references/editing.md

控制数据何时以及如何提交：

• 提交模式（LostFocus、PropertyChanged、Manual）
• CommitMode 属性配置
• 使用 Commit() 方法以编程方式提交
• 只读字段和禁用的编辑器
• ValueChanged 事件处理
• 以编程方式更新数据对象
• 双向数据绑定行为
• 表单重置和取消操作

阅读时机： 需要控制表单更改何时保存到数据对象，或实现保存／取消逻辑时。

---

浮动标签布局

📄 阅读： references/floating-label-layout.md

实现现代浮动标签设计：

• 浮动标签功能概述
• 在编辑器上启用浮动标签
• 标签动画行为（聚焦时浮动）
• Float 模式配置选项
• 浮动标签样式设置
• 浮动标签 UX 最佳实践
• 与不同编辑器类型的兼容性

阅读时机： 想要实现 Material Design 风格的浮动标签，打造现代外观时。

---

本地化

📄 阅读： references/localization.md

支持表单使用多种语言：

• 本地化概述和设置
• 资源文件（.resx）配置
• 特定区域性的字符串和消息
• 本地化错误消息
• 本地化标签和提示词
• 运行时语言切换
• 特定平台的本地化注意事项

何时阅读： 需要创建多语言表单或支持国际用户时。

---

从右到左支持

📄 阅读： references/right-to-left.md

为阿拉伯语、希伯来语和其他从右到左书写的语言实现 RTL 布局：

• RTL 支持概述
• 使用 FlowDirection 启用 RTL 布局
• 编辑器和控件的 RTL 行为
• 标签和验证消息的 RTL 支持
• RTL 的文化注意事项
• 测试和调试 RTL 布局

何时阅读： 需要支持阿拉伯语或希伯来语等从右到左书写的语言时。

---