syncfusion-angular-form-renderer

用途

Syncfusion Angular Form Renderer 用于在 Angular 中生成、排查和扩展基于 schema 的表单。该组件围绕单个 JSON schema 构建，schema 中声明字段定义、布局、校验、动态行为和提交动作。

适用任务包括：

创建新的 Angular 应用并安装 Syncfusion Form Renderer 包
用 properties、layout 和 settings 定义表单
添加 required、pattern、minLength、maxLength 或自定义校验规则
根据先前答案显示或隐藏字段
构建依赖下拉或级联选项列表
用 minMaxRange 依据另一个字段限制数值或日期范围
用 expressionValue 和外部引用计算值
处理 submit、reset 和自定义按钮动作
用 allowMultiple 和 buttonsGroups 定义分组按钮动作
用自定义 Angular 模板替换内置组件

快速开始

安装包：

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

在 Angular 组件中导入模块和 schema 类型：

import { Component } from '@angular/core';
import { FormRendererAllModule, Schema } from '@syncfusion/ej2-angular-form-renderer';

将 schema 绑定到组件并处理 submit 事件：

<ejs-form-renderer [schema]="schema" (submit)="onSubmit($event)"></ejs-form-renderer>

定义表单 schema：

public schema: Schema = {
  version: '0.1.0',
  properties: {
    emailAddress: {
      id: 'textbox_1',
      name: 'emailAddress',
      type: 'string',
      label: 'Email Address',
      textboxType: 'email',
      required: true,
      widget: 'textbox'
    },
    submit: {
      id: 'submit_1',
      name: 'submit',
      type: 'button',
      label: 'Submit',
      buttonType: 'submit',
      widget: 'button'
    }
  },
  layout: [
    { type: 'field', propertyId: 'emailAddress' },
    { type: 'field', propertyId: 'submit' }
  ],
  settings: { name: 'Registration Form' }
};

保持表单声明式：校验、条件和表达式放在使用它们的字段上。

文档主题

入门

涉及 Angular CLI 设置与项目创建、安装包和主题 CSS、基本 schema 与提交示例，以及用 ng serve 在本地运行应用。

表单 schema 与字段模型

包括根对象结构：version、properties、layout、settings；支持的全部字段组件、数据类型及其提供的 UI 交互；按客户偏好选择组件的逐字段呈现选项；面板、表格、选项卡和卡片等布局示例，包括容器子项如何引用字段；字段 ID、名称、标签、类型及常见元数据。

校验

包括 required、minLength、maxLength、pattern 等内置规则；用 customValidation 和 valid = ... 实现自定义校验；校验在提交时还是在变更时运行。

条件行为

包括 visibleWhen、hideWhen、requiredWhen、readOnlyWhen、disabledWhen；规则 schema、嵌套 and / or 组、完整运算符列表及各规则效果；逐组件支持矩阵，说明哪些条件类型被支持或被忽略；setValueWhen 与 choiceBasedField 配置概念。

动态表达式

包括用 expressionValue 从其他字段派生值；字段引用、数组索引、分组、三元语法及算术/比较/逻辑运算符；PI、TRUE、FALSE、NULL 和 Math 等常量；聚合、数学、字符串和日期函数（含 DATEFORMAT）及其语法和返回类型。

依赖下拉

包括用 choiceBasedField 实现级联选项；primaryFieldId 和 choiceMapping；值缺失时 showAllWhenNotMapped 的行为。

基于其他字段的范围逻辑

包括使用字段引用对象的 minMaxRange；由另一个字段驱动的数值和日期范围约束；应用固定 min / max 规则与跨字段范围规则的区别。

远程数据绑定

包括 dropdown、multiselect 和 checkbox group 字段的远程选项源；URL 适配器、响应 dataPath、请求头及动态搜索/过滤值；search、sort、filter、skip 和 take 查询配置。

数据网格特性

包括静态和远程网格数据源；列编辑、校验、自定义校验和表达式；由其他表单字段驱动的条件数据源；网格 search、sort、filter 和分页配置。

表单动作与模板

包括 buttonType: 'submit'、'reset' 和 'button'，以及分组按钮动作；submit / buttonClick 行为和自定义逻辑；submit、change、buttonClick、failure 和 created 事件及其参数和生命周期行为；allowMultiple 与 buttonsGroups 的项标签、动作、样式、图标和禁用状态；按组件类型、字段名称或模板 ID 使用 <e-customwidgetsetting> 的自定义组件模板；全部 CustomWidgetSettingModel 属性和 HTML sanitizer 行为；带可聚焦控件、绑定值和 setFieldValue 同步的原生或自定义组件模板；在不强制渲染时自动聚焦的情况下保留活动输入焦点；从自定义字段模板更新 Form Renderer 状态。

常见模式

保持 name 值稳定，因为它们会被用作载荷键和表达式中的引用。
使用 layout 对象把字段组织到面板、表格、选项卡或卡片中。
当控件依赖另一个字段时，级联下拉优先用 choiceBasedField，动态 min/max 限制优先用 minMaxRange。
把校验和条件逻辑存放在其影响的字段旁边，使 schema 易于推理。
最终校验优先用 buttonType: 'submit'；需要自定义动作逻辑时用 buttonType: 'button'。

实现检查清单

构建或修复 Form Renderer schema 时，确认：

每个字段都有唯一的 name 和 id
layout 引用的 propertyId 都有效
支持的组件与字段类型匹配
条件字段使用有效的字段引用和运算符
动态表达式用 {name} 语法引用已存在的字段名
自定义校验为 valid 赋值 true 或字符串错误消息
需要表单提交时包含提交按钮

本技能旨在帮助依据文档生成可用的 Angular Form Renderer 表单，而不虚构不支持的 schema 属性。