内置表单引擎

为了方便开发者在定制化要求不高的场景使用,Reactive Form 内置了一个基于核心扩展成的引擎, 内置引擎被封装在 Form 模型内,包含了常用的表单成员类型,如文本输入、数字输入、单选、多选等。 本章主要对内置引擎所包含的各成员类型以及它们之间的关系作出介绍。

Fieldset

Fieldset 类型成员与 HTML 中的 <fieldset> 标签类似,主要作用是用来包裹各种输入项类型成员,形成有组织的层级结构。

Fieldsetschema 属性范围包括:

  • name: 同辈成员间唯一性标识,默认为成员 id,不接受被设定为 DSL
  • label: 标题,默认为 I18n 定义的 locale,不接受被设定为 DSL
  • description: 描述,默认为 I18n 定义的 locale,不接受被设定为 DSL

具体用法请看下例。

输入项类型

Fieldset 成员的子级应是各种输入项成员,与 HTML 中 <input> 标签类似,被包裹的各类成员可被用于接收不同数据类型的输入。

在内置引擎中,注册好的输入项类型 schema 属性范围包括:

  • name: 同辈成员间唯一标识,默认为成员 id,不接受被设定为 DSL
  • label: 标题,默认为 I18n 定义的 locale,不接受被设定为 DSL
  • value: 输入值,默认为 null,不接受被设定为 DSL
  • placeholder: 占位符,默认为 I18n 定义的 locale,不接受被设定为 DSL
  • options: 输入值可选项,默认为只有一个元素的数组,不接受被设定为 DSL
  • validation: 输入值校验规则,默认为 null,当不为空时,会对 value 当前值进行校验。
  • calculation: 输入值计算规则,默认为 null,当不为空时,value 会自动被设定为计算得出的值。
  • editable: 是否可输入,默认为 true
  • visible: 是否可见,默认为 true

当输入项成员的属性被设定为不合规的值时,其存储空间中会被写入错误信息, 根据类型不同,以上属性的支持范围有所不同,各类型成员支持的属性和具体用法如下:

文本输入项

TextFieldMultilineTextField 均为文本输入项类型,成员接受 String 作为输入值。 二者 schema 定义类似,不同的是语意上的差异,MultilineTextField 强调了多行文本的语意性。

数字输入项

NumberField 是数字输入项类型,接受 Number 作为输入值。

单项选择输入项

RadioFieldSingleSelectField 均为单项选择输入项类型,接受 String 作为输入值, 且必须在 options 范围内。二者 schema 定义类似,不同的是语意上的差异, RadioField 强调单选框选择,SingleSelectField 强调下拉菜单选择。 另外, SingleSelectField 还多了一个 placeholder 属性。

多项选择输入项

CheckboxFieldMultipleSelectField 均为多项选择输入项, 接受元素为 StringArray 作为输入值,且元素必须在 options 范围内。 二者 schema 定义类似,不同的是语意上的差异, CheckboxField 强调复选框选择,MultipleSelectField 强调下拉菜单选择。

子表单

子表单通常指的是,表单中嵌套的一组结构相同,可被复制的输入项。 比如在一张个人履历调查表中,教育经历可以填写多条记录,每条记录的结构相同,都包含学校、学历、周期等信息。 内置引擎包含的成员类型中,提供了子表单的处理能力。这些类型是 SubformSubformFieldset 以及 Subform*Field

Subform*Field 是基于元编程的方式, 使用其它输入项类型动态生成的新类型,schema 的定义并没有被修改, 举例来说 SubformTextField 是基于 TextField 类型生成的,其 schemaTextField 相同。

SubformFieldset 的作用只是包裹一组 Subform*Field 形成一条记录, 因此,其本身并没有显示地定义 schema

Subformschema 属性范围包括:

  • name: 同辈成员间唯一性标识,默认为成员 id,不接受被设定为 DSL
  • label: 标题,默认为 I18n 定义的 locale,不接受被设定为 DSL
  • editable: 包裹的 Subform*Field是否可输入,默认为 true
  • visible: 是否可见,默认为 true

为了确保子表单中不同记录间结构的一致性,当 SubformFieldset 被创建后, 会克隆进一组其它 SubformFieldset 中已存在的 Subform*Field; 当 SubformFieldset 中被添加进 Subform*Field, 其它 SubformFieldset 也都会被复制进一个属性设定值相同的 Subform*Field; 当 SubformFieldset 中的 Subform*Field 被删除,其它 SubformFieldset 中同一 order 位置 的 Subform*Field 也都会被删除; 当 Subform*Field 除了 value 外的属性设定值变更, 其它 SubformFieldset 中同一 order 位置的 Subform*Field 的同一属性都会被设定为相同的值。

我们通过下面的示例来具体了解子表单的用法,读者可以尝试修改代码来体会上文描述的行为。

小结

  • Fieldset 主要用来包裹各种输入项类型成员,形成有组织的层级结构。
  • 输入项成员被用于接收不同数据类型的输入,当输入项成员的属性被设定为不合规的值时,会向其存储空间中写入错误信息。
  • 子表单是表单中嵌套的一组结构相同,可被复制的输入项。
  • Subform*Field 类型成员,除更新 value 设定值外,其它操作会同步执行于相同 Subform 的各 SubformFieldset 中。

通过阅读本章,我们了解了 Reactive Form 内置引擎提供的成员,以及这些成员的能力和行为。 事实上,内置引擎支持扩展成员类型,这意味着我们可以基于内置引擎扩展更丰富的表单能力, 在下一章中,我们将一起探索如何 扩展内置 Form 引擎