syncfusion-react-form-builder

Syncfusion React Form Builder

当用户需要使用 Syncfusion Form Builder 创建、排查问题或扩展可编辑的 React 表单时，请使用此技能。Form Builder 是一款可视化设计器，可生成由 schema 驱动的表单定义：用户可以将字段拖到画布上，在属性面板中进行配置，预览结果，并导出 schema 以供 Form Renderer 使用。

何时使用此技能

当用户需要执行以下操作时，请使用此技能：

• 创建 Vite React 应用并安装 Syncfusion Form Builder 包
• 渲染包含工具箱、画布、属性面板、代码视图和预览的可视化表单设计器
• 通过 schema 属性加载初始表单
• 在 properties 中定义字段，在 layout 中排列字段，并设置表单级 settings
• 配置 Form Builder 属性，例如导出、预览、持久化、RTL、模式、模板和工具箱项目
• 从 Basic、Advanced 和 Layout 工具箱类别中选择字段
• 自定义字段属性，添加或隐藏属性面板条目，并刷新设计器
• 定义自定义工具箱模板，并通过 setFieldValue 同步模板值
• 处理字段拖动开始、拖动经过、放置和属性更改事件
• 查看、复制、导入或导出生成的 JSON schema
• 准备包含验证、条件、表达式、依赖下拉列表、动态范围、远程数据或 Data Grid 字段的 schema

此技能用于设计和编辑表单。当主要任务是为最终用户渲染已完成的 schema、处理提交的值或配置渲染器表单操作时，请使用 React Form Renderer 技能。

文档与导航指南

组件 API 和事件

📄 阅读： references/getting-started.md

• 所有 Form Builder 属性、类型和默认值
• Simple 和 Developer 模式
• schema、导出、预览、持久化、RTL、模板和工具箱配置

入门指南

📄 阅读： references/getting-started.md

• Vite 和 React 设置及 CSS 主题导入
• Form Builder 基本用法
• 将表单 schema 绑定到组件
• 用于创建表单的最小可运行示例

Schema 和初始表单设置

📄 首先阅读： references/form-schema.md

• schema 属性和根 schema 结构
• 在 properties 中定义字段，以及在 layout 中设置渲染顺序
• 表单设置、支持的控件和布局容器
• 将每个请求的字段与文档中对应的 widget 和 type 匹配

当客户要求创建带有初始表单的 React Form Builder 时，请根据 references/getting-started.md 创建 Vite 和 React 组件设置，然后使用 references/form-schema.md 定义初始 schema。如果所需 schema 需要相应功能，请阅读以下参考资料：

• 验证规则： references/validations.md
• 条件行为： references/conditions.md
• 计算值： references/expressions.md
• 依赖下拉列表： references/dependent-dropdown.md
• 动态数值/日期/时间范围限制： references/min-max-range.md
• 远程下拉列表、多选或复选框组数据： references/remote-data-binding-in-components.md
• Data Grid 字段和数据源： references/data-grid-features.md

字段组件面板

📄 阅读： references/field-components-panel.md

• Fields 和 Templates 选项卡
• Basic、Advanced 和 Layout 类别
• 搜索/筛选行为和工具箱自定义
• 自定义模板库和 formTemplates

属性面板

📄 阅读： references/property-panel.md

• 面板在选中字段时显示的时机
• 显示、验证、条件、布局和数据选项卡
• setProperty 和 getProperty 的用法
• 自动保存和属性刷新行为

预览和 JSON

📄 阅读： references/preview-tab.md

• 预览选项卡的工作流
• 使用 enablePreview 禁用预览
• JSON 架构审查和复制操作

模板

📄 阅读： references/templates.md

• 使用 toolboxItems 定义自定义工具箱模板
• 导出时使用 templateId
• 将第三方组件映射到架构

表单设置

📄 阅读： references/form-settings.md

• 全局表单标题和宽度
• 隐藏标签、尺寸和浮动标签类型等布局级设置
• 应用表单级配置，而不影响单个字段

导出和导入

📄 阅读： references/export-import.md

• 导出架构，以便 Form Renderer 重用
• 将现有架构导入回 Form Builder
• 使用 allowExport 禁用导出

快速开始

1. 安装软件包：

npm install @syncfusion/ej2-react-form-builder @syncfusion/ej2-material3-theme

2. 导入组件并绑定初始架构：

import { FormBuilderComponent } from '@syncfusion/ej2-react-form-builder';
import '@syncfusion/ej2-material3-theme/styles/material3.css';

const formSchema = {
  version: '0.1.0',
  properties: {
    emailAddress: {
      id: 'textbox_1785491685456_167',
      name: 'emailAddress',
      type: 'string',
      label: 'Email Address',
      textboxType: 'email',
      required: true,
      placeholder: 'Enter your email',
      widget: 'textbox'
    }
  },
  layout: [{ type: 'field', propertyId: 'emailAddress' }],
  settings: { name: 'Untitled Form' }
};

export default function App() {
  return <FormBuilderComponent schema={formSchema} />;
}

3. 使用 npm run dev 启动 Vite 应用，然后使用工具箱和属性面板编辑表单。请阅读 references/getting-started.md，了解项目创建、主题设置和完整的初始配置。

常见模式

自定义工具箱

使用 toolboxCategories 控制工具箱中显示哪些字段类型，以及它们归属的类别。

import { FormBuilderComponent } from '@syncfusion/ej2-react-form-builder';
import { ComponentCategory, FormWidgetType } from '@syncfusion/ej2-form-builder';

const toolboxCategories = [
  {
    category: ComponentCategory.Basic,
    items: [FormWidgetType.Textbox, FormWidgetType.Textarea]
  },
  {
    category: ComponentCategory.Advanced,
    items: [FormWidgetType.Date, FormWidgetType.DateRange]
  }
];

动态添加属性

使用 setProperty 为控件添加自定义属性，并使用 refresh() 更新面板。

formBuilderRef.current?.setProperty(FormWidgetType.Textarea, {
  key: 'enableRtl',
  label: 'Enable RTL',
  type: 'boolean',
  default: false
});

注册自定义模板

在 toolboxItems 中定义第三方自定义控件，并在值发生变化时调用 setFieldValue。

<FormBuilderComponent
  toolboxItems={[{ type: FormWidgetType.Textbox, template: inputTemplate }]}
/>;

使用预览和 JSON 输出

切换到“预览”选项卡以验证布局和交互，然后打开 JSON 选项卡检查导出的架构，并复制以供 Form Renderer 使用。

常见模式

• 将每个字段保存在 properties 中，并在 layout 中通过其 propertyId 引用。
• 为每个字段指定稳定且唯一的 name 和 id；在条件、表达式和依赖数据中使用文档说明的 id 和 name 引用。
• 根据 references/form-schema.md 中受支持的架构清单，为每个请求的字段匹配 widget 和 type。
• 使用 toolboxCategories 或 toolboxItems 控制可在可视化工具箱中使用的字段。
• 使用 formTemplates 创建可重用的完整架构，并使用自定义工具箱模板定义第三方控件。
• 在预览中验证表单，检查 JSON 选项卡，并仅在架构和布局正确后导出。
• 使用 API 事件负载获取设计器交互状态；使用 Form Renderer 事件获取运行时值和提交行为。

实施检查清单

构建或修复 Form Builder 表单时，请确认：

• 已安装 React 软件包和主题，并已导入 FormBuilderComponent
• schema 值是对象、JSON 字符串或受支持的架构实例
• 每个字段都有唯一的 name、稳定的 id、受支持的 widget 和匹配的 type
• 每个 layout 字段节点都引用有效的 propertyId
• 布局容器保留在 layout 中，其子字段保留在 properties 中
• 验证、条件、表达式、范围和数据源均使用文档说明的引用结构
• 自定义模板使用 setFieldValue 更新 Form Builder 状态
• 根据所需工作流启用或禁用预览和导出
• 自定义组件引用采用文档说明的 React useRef 模式

典型工作流

• 首先创建基础架构，并将其加载到构建器中。
• 使用工具箱分类和预定义模板来组织表单设计。
• 在右侧面板中编辑字段属性，以设置验证、布局和显示行为。
• 导出架构前，先在预览中验证最终表单。
• 之后重新导入架构，以继续编辑或调整生成的表单。