syncfusion-angular-form-builder

用途

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

适用场景包括：

创建 Angular 应用并安装 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、处理提交值或配置渲染器表单操作，应使用 Form Renderer 技能。

主要能力与文档导航

资料按以下参考文档组织：

getting-started.md：组件 API 与事件（所有 Form Builder 属性、类型和默认值；简单模式与开发者模式；schema、export、preview、persistence、RTL、templates 和 toolbox 配置；字段 drag-start、drag-over、drop 和 property-changed 事件负载），以及 Angular 设置与模块注册、基础用法、将表单 schema 绑定到组件、最小可用示例。
form-schema.md（建议优先阅读）：schema 属性与根 schema 结构、properties 中的字段定义与 layout 中的渲染顺序、表单设置、支持的 widget 和布局容器、将请求的字段匹配到已记录的 widget 和类型。
validations.md：验证规则。
conditions.md：条件行为。
expressions.md：计算值。
dependent-dropdown.md：依赖下拉。
min-max-range.md：动态数值/日期/时间边界。
remote-data-binding-in-components.md：远程下拉、多选或复选框组数据。
data-grid-features.md：Data Grid 字段和数据源。
field-components-panel.md：Fields 与 Templates 标签页、Basic/Advanced/Layout 分类、搜索/过滤行为与工具箱自定义、自定义模板库和 formTemplates。
property-panel.md：面板在选中字段时出现、Display/Validation/Conditions/Layout/Data 标签页、setProperty 与 getProperty 模式、自动保存与属性刷新行为。
preview-tab.md：预览标签页工作流、使用 enablePreview 禁用预览、JSON schema 查看与复制操作。
templates.md：使用 e-toolboxitemsetting 定义自定义工具箱模板、导出时使用 templateId、将第三方组件映射到 schema。
form-settings.md：全局表单标题和宽度、布局级设置（如 Hide Label、Size、Float Label Type）、在不影响单个字段的情况下应用表单级配置。
export-import.md：导出 schema 供 Form Renderer 复用、将已有 schema 导回 Form Builder、使用 allowExport 禁用导出。

快速开始

安装包：

ng add @syncfusion/ej2-angular-form-builder

导入 Form Builder 模块并绑定初始 schema：

import { Component, ViewChild } from '@angular/core';
import { FormBuilderComponent, FormBuilderModule } from '@syncfusion/ej2-angular-form-builder';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [FormBuilderModule],
  template: `
    <ejs-form-builder #formObj [schema]="schema"></ejs-form-builder>
  `
})
export class AppComponent {
  @ViewChild('formObj') public formObj?: FormBuilderComponent;

  public schema = {
    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'
    }
  };
}

使用 ng serve 启动 Angular 应用，然后使用工具箱和属性面板编辑表单。主题设置、应用创建和完整初始设置见 references/getting-started.md。

常见模式

自定义工具箱：使用 toolboxCategories 控制工具箱中出现的字段类型及其分组分类。

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

动态添加属性：使用 setProperty 为 widget 添加自定义属性，并用 refresh() 更新面板。

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

注册自定义模板：在 e-toolboxitemsettings 中定义第三方自定义控件，并在值变化时调用 setFieldValue。

<e-toolboxitemsetting [type]="formType">
  <ng-template #template let-data>
    <input [value]="data.value || ''" (input)="onInputChange($event, data)" />
  </ng-template>
</e-toolboxitemsetting>

使用预览和 JSON 输出：切换到 Preview 标签页验证布局和交互，然后打开 JSON 标签页查看导出的 schema 并复制，供 Form Renderer 使用。

其他常见做法：

将每个字段保留在 properties 中，并在 layout 中通过其 propertyId 引用；
为每个字段提供稳定的唯一 name 和 id，条件、表达式和依赖数据使用已记录的 id 与 name 引用；
将请求的字段 widget 和类型匹配到 references/form-schema.md 中支持的 schema 清单；
使用 toolboxCategories 或 toolboxItems 控制可视化工具箱中可用的字段；
使用 formTemplates 保存可复用的完整 schema，使用自定义工具箱模板处理第三方控件；
在 Preview 中验证表单，检查 JSON 标签页，仅在 schema 与 layout 正确后再导出；
使用 API 事件负载获取设计器交互状态，使用 Form Renderer 事件处理运行时值和提交行为。

实现清单

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

Angular 包和主题已安装，且 Form Builder 模块已导入；
schema 值为对象、JSON 字符串或受支持的 schema 实例；
每个字段都有唯一 name、稳定 id、受支持的 widget 和匹配的 type；
每个 layout 字段节点引用有效的 propertyId；
布局容器保留在 layout 中，其子字段保留在 properties 中；
验证、条件、表达式、范围和数据源使用已记录的引用结构；
自定义模板通过 setFieldValue 更新 Form Builder 状态；
根据所需工作流启用或禁用预览与导出；
drag 和 property-change 处理器使用 references/getting-started.md 中的事件名称和负载成员。

典型工作流

先创建基础 schema 并加载到 builder 中。
使用工具箱分类和预定义模板组织表单设计。
在右侧面板编辑字段属性，处理验证、布局和显示行为。
在导出 schema 前通过 Preview 验证最终表单。
之后可重新导入 schema 继续编辑或调整生成的表单。

限制

资料未提供价格、收费、平台兼容范围或效果数据。使用本技能时应以 Form Builder 的设计与编辑为边界，终端用户渲染与提交处理不属于本技能范围。