syncfusion-react-form-builder

用途

Syncfusion React Form Builder 是一个可视化表单设计器，用于生成由 schema 驱动的表单定义。用户可以把字段拖拽到画布上，在属性面板中配置字段，预览结果，并导出 schema 供 Form Renderer 使用。

本技能适用于需要创建、排查或扩展可编辑 React 表单的场景，具体包括：

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

本技能面向表单的设计与编辑。如果主要任务是向最终用户渲染已完成的 schema、处理提交值或配置渲染器表单动作，应使用 React Form Renderer 技能。

主要能力

组件 API 与事件

涵盖 Form Builder 的全部属性、类型和默认值；Simple 与 Developer 模式；schema、export、preview、persistence、RTL、templates 和 toolbox 配置。

快速开始

包含 Vite 与 React 环境搭建及 CSS 主题引入、Form Builder 基本用法、将表单 schema 绑定到组件，以及编写表单的最小可运行示例。

Schema 与初始表单

说明 schema 属性与根 schema 结构、properties 中的字段定义与 layout 中的渲染顺序、表单设置、支持的控件与布局容器，以及如何把每个所需字段匹配到文档中记录的控件和类型。

当客户需要一个带初始表单的 React Form Builder 时，先按快速开始创建 Vite 与 React 组件环境，再用 schema 参考定义初始 schema。若所需 schema 需要以下行为，则查阅对应参考：

• 校验规则：validations
• 条件行为：conditions
• 计算值：expressions
• 依赖下拉：dependent-dropdown
• 动态数值/日期/时间边界：min-max-range
• 远程下拉、多选或复选框组数据：remote-data-binding-in-components
• Data Grid 字段与数据源：data-grid-features

字段组件面板

涵盖 Fields 与 Templates 选项卡、Basic/Advanced/Layout 分类、搜索过滤行为与工具箱自定义、自定义模板库与 formTemplates。

属性面板

说明面板在选中字段时出现的时机，Display、Validation、Conditions、Layout 和 Data 选项卡，setProperty 与 getProperty 用法，以及自动保存与属性刷新行为。

预览与 JSON

包含预览选项卡工作流、用 enablePreview 禁用预览、JSON schema 查看与复制操作。

模板

说明用 toolboxItems 定义自定义工具箱模板、导出时使用 templateId，以及把第三方组件映射到 schema。

表单设置

涵盖全局表单标题与宽度、布局级设置（如 Hide Label、Size、Float Label Type），以及在不影响单个字段的情况下应用表单级配置。

导出与导入

说明导出 schema 供 Form Renderer 复用、把已有 schema 导入回 Form Builder，以及用 allowExport 禁用导出。

使用方式

安装包：

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

导入组件并绑定初始 schema：

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} />;
}

用 npm run dev 启动 Vite 应用，然后使用工具箱和属性面板编辑表单。项目创建、主题设置和完整初始配置见快速开始参考。

常见模式

自定义工具箱：用 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 输出：切换到 Preview 选项卡验证布局与交互，再打开 JSON 选项卡查看导出的 schema，并复制用于 Form Renderer。

常见做法

• 把每个字段放在 properties 中，并在 layout 中通过其 propertyId 引用
• 为每个字段设置稳定唯一的 name 和 id；条件、表达式和依赖数据使用文档记录的 id 与 name 引用
• 把每个所需字段的控件和类型匹配到 schema 参考中支持的清单
• 用 toolboxCategories 或 toolboxItems 控制可视化工具箱中可用的字段
• 用 formTemplates 存放可复用的完整 schema，用自定义工具箱模板承载第三方控件
• 在 Preview 中验证表单，检查 JSON 选项卡，确认 schema 与布局正确后再导出
• 设计器交互状态使用 API 事件负载；运行时值与提交行为使用 Form Renderer 事件

实现检查清单

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

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

典型工作流

1. 先创建基础 schema 并加载到构建器中
2. 使用工具箱分类和预定义模板组织表单设计
3. 在右侧面板编辑字段属性，配置校验、布局和显示行为
4. 在 Preview 中验证最终表单，然后导出 schema
5. 之后可重新导入 schema 继续编辑或调整已生成的表单

适用场景

• 需要在 React（Vite）项目中搭建可视化表单设计器
• 需要以 schema 驱动方式定义、编辑和导出表单
• 需要为表单配置校验、条件、表达式、依赖下拉、动态范围、远程数据或 Data Grid 字段
• 需要自定义工具箱、属性面板或第三方控件模板
• 需要排查或扩展已有的 Form Builder 表单

限制

• 本技能面向表单的设计与编辑；渲染成品 schema、处理提交值或配置渲染器动作应使用 React Form Renderer 技能
• 字段的 widget 与 type 必须匹配文档记录的受支持清单
• 自定义模板需通过 setFieldValue 同步状态，否则设计器状态可能不一致
• 关于收费、价格、平台支持范围等具体信息，资料中暂未提供