开始使用

@delon/form 是一个基于 JSON Schema 标准的动态构建表单。

特性

  • 符合 JSON Schema 标准

  • 基于 ng-zorro-antd 基础组件库

  • 秉承 Ant Design 价值观

  • 二十几种小部件

  • 可自定义小部件满足业务需求

  • 无任何第三方依赖,可适用所有 antd 项目

如何阅读

在开始之前需要知道文档的一些简单编写规则:

  • 代码以 schema. 开头的表示 JSON Schema 对象属性

  • 代码以 ui. 开头的表示 UI 对象属性

  • 部分小部件数据源分为 静态实时 两类

    • 静态 理解为 schema.enum 值,是符合 JSON Schema 标准,且限数组格式 any[]

    • 实时 理解为 ui.asyncData 值,非 JSON Schema 标准,格式 (input?: any) => Observable<SFSchemaEnumType[]>

如何使用

安装 @delon/form 依赖包:

  1. yarn add @delon/form

导入 DelonFormModule 模块:

  1. import { DelonFormModule } from '@delon/form';
  2. @NgModule({
  3. imports: [
  4. DelonFormModule.forRoot()
  5. ]
  6. })
  7. export class AppModule { }

虽然默认 @delon/form 校验是 ajv,但这并不是唯一的选择,你可以覆盖 SchemaValidatorFactory 使用其他校验类库,所以 ajv 并没有强制依赖;其实从另一个点来看将这种第三方类库统一在 scripts 加载才是更合理的,因此你依然要自己安装 ajv 并在 angular.json 中导入它:

  1. yarn add ajv @types/ajv

angular.json

  1. "scripts": [
  2. "node_modules/ajv/dist/ajv.bundle.js"
  3. ]

全局配置

请参考全局配置,成员如下:

成员说明类型默认值
[ajv]ajv 参数Ajv.Options-
[ingoreKeywords]是否忽略某些数据类型校验(所有类型string[][ ‘type’, ‘enum’ ]
[liveValidate]是否实时校验booleantrue
[autocomplete]指定表单 autocompleteon,offnull
[firstVisual]是否立即呈现错误视觉booleanfalse
[onlyVisual]是否只展示错误视觉不显示错误文本,并取消错误文本间距booleanfalse
[errors]自定义通用错误信息{ [ key: string ]: string }ERRORSDEFAULT
[ui]默认全局布局SFUISchemaItem-
[size]元素组件大小,用于 nzSizedefault,large,small-
[button]按钮风格SFButton{submit:’提交’,submit_type:’primary’,reset:’重置’,reset_type:’default’}
[uiDateStringFormat]date小部件:type=”string” 且不指定 schema.formatui.format 时日期格式stringyyyy-MM-dd HH:mm:ss
[uiDateNumberFormat]date小部件:type=”number” 且不指定 schema.formatui.format 时日期格式,默认:T 13位Unix TimestampstringT
[uiTimeStringFormat]time小部件:type=”string” 且不指定 schema.formatui.format 时日期格式stringHH:mm:ss
[uiTimeNumberFormat]time小部件:type=”number” 且不指定 schema.formatui.format 时日期格式,默认:T 13位Unix Timestamp,日期统一使用 1970-01-01stringT
[uiEmailSuffixes]指定 format: ‘email’ 的默认Email后缀string[][‘qq.com’, ‘163.com’, ‘gmail.com’, ‘126.com’, ‘aliyun.com’]

构建一个邮箱、姓名表单:

  1. @Component({
  2. selector: 'app-home',
  3. template: `
  4. <sf [schema]="schema" (formSubmit)="submit($event)"></sf>
  5. `
  6. })
  7. export class HomeComponent {
  8. schema: SFSchema = {
  9. properties: {
  10. email: {
  11. type: 'string',
  12. title: '邮箱',
  13. format: 'email',
  14. maxLength: 20
  15. },
  16. name: {
  17. type: 'string',
  18. title: '姓名',
  19. minLength: 3
  20. }
  21. }
  22. };
  23. submit(value: any) { }
  24. }

API

sf

参数说明类型默认值
[layout]表单布局,等同 nzLayout‘horizontal’,’vertical’,’inline’‘horizontal’
[schema]必填项 JSON SchemaSFSchema-
[ui]UI SchemaSFUISchema-
[formData]表单默认值any-
[mode]表单模式,细节见常见问题‘default’,’search’,’edit’‘default’
[button]按钮SFButton|’none’{}
[firstVisual]是否立即呈现错误视觉booleantrue
[liveValidate]是否实时校验,false 提交时检验booleantrue
[autocomplete]指定表单 autocomplete‘on’,’off’null
[disabled]是否禁用状态booleanfalse
[loading]是否加载状态,当 true 重置按钮禁止状态,提交按钮加载状态booleanfalse
[noColon]是否不显示 label 后面的冒号booleanfalse
[compact]是否紧凑booleanfalse
[cleanValue]是否清理未定义 Schema 的数据booleanfalse
(formChange)数据变更时回调EventEmitter<{}>-
(formValueChange)值数据变更时回调EventEmitter<SFValueChange>-
(formSubmit)提交表单时回调EventEmitter<{}>-
(formReset)重置表单时回调EventEmitter<{}>-
(formError)表单校验结果回调EventEmitter<ErrorData[]>-

SFButton

参数说明类型默认值
[submit]提交按钮文本string提交
[submit_type]提交按钮类型stringprimary
[submit_icon]提交按钮图标SFButtonIcon-
[reset]重置按钮文本string重置
[reset_type]重置按钮类型stringdefault
[reset_icon]重置按钮图标SFButtonIcon-
[search]搜索按钮文本string搜索
[edit]编辑按钮文本string保存
[render]按钮样式SFRenderButton-

SFValueChange

参数说明类型默认值
[value]总是返回完整的数据SFValue-
[path]当前触发路径string, nullnull
[pathValue]当前触发路径对应值SFValue-

组件方法

参数说明返回值
valid表单是否有效boolean
value表单值any
refreshSchema刷新 JSON Schemavoid
reset重置表单void
validator手动校验一次表单void
getProperty根据路径获取表单元素属性FormProperty
getValue根据路径获取表单元素当前值any
setValue根据路径设置某个表单元素属性值,若路径不存在会产生异常this

注: 所有 path 采用 / 来分隔,例如:/user/name/arr/0/name

按钮说明

注意事项

  • 值为 nullundefined 表示手动添加按钮,但保留容器

  • 值为 none 表示手动添加按钮,且不保留容器

  • 使用 spanLabelFixed 固定标签宽度时,若无 render.class 则默认为居中状态

自定义

当你希望自定义按钮时,务必设置 button 值为 null

  1. <sf #sf [button]="null">
  2. <button type="submit" nz-button [disabled]="!sf.valid">保存</button>
  3. <button (click)="sf.reset()" type="button" nz-button>重置</button>
  4. </sf>

常见问题

mode有什么作用?

mode 只是快捷作用,且优先级高于一切,规则如下:

  • default 默认模式,什么也不做

  • search 搜索模式,自动设置 layout: inlinefirstVisual: falseliveValidate: falsebutton.submit: '搜索'

  • edit 编辑模式,自动设置 layout: horizontalfirstVisual: falseliveValidate: truebutton.submit: '保存'

Schema国际化

sf 并不支持任何 Schema 国际化动作,这是因为本身 Schema 是一组 JSON 值,国际化的实现只需要提供不同语言版本即可。