Schema

写在前面

JSON Schema 是一种标准的定义 JSON 数据结构的规范，并不包含对这些规范转换成表单具体说明，@yelon/form 也是根据自己的理解并结合 ng-zorro-antd 现有数据录入组件库产生的动态构建表单类库。

JSON Schema 始终都必须有一个类型为 type="object" 作为根节点，因此一个最简单的 Schema 结构至少是：

schema = {
  type: 'object', // 可有可无，默认会强制为 `object`
  properties: {}
}

在描述 Schema 说明之前，有必要对表单元素与 Schema 之前的联系做一个系统性说明。

我们知道，表单是由一组HTML元素组件，每一个元素对应一个 Schema 属性，属性有自己的数据类型、格式信息、视觉信息等，但这些信息不足以表述 ng-zorro-antd 所提供的丰富API接口。为了更好利用这些API接口，@yelon/form 除了实现绝大部分 JSON Schema 标准以外，额外唯一增加了一个 ui 属性用于表述属性如何渲染的问题。

无污染

当然若你对标准有非常严格，或者 JSON Schema 数据结构是来自后端的产生时，可以通过 <sf [ui]="ui"> 来额外对当前 JSON Schema 添加 UI 渲染。例如：

schema = {
  properties: {
    url: {
      type: 'string',
      title: 'Web Site'
    }
  }
}

一个URL属性，若我们不希望用于添加 https:// 前缀的情况下，就单纯的 JSON Schema 结构是无法表述，而 nz-input 又支持非常丰富的前后缀文本，则我们可以为 ui 定制并增加 https:// 的前缀文本：

ui = {
  $url: {
    addOnBefore: 'https://'
  }
}

ui 本身也是一个 JSON 结构，为了区分 JSON Schema 属性名的对应关系，必须统一对属性名加上 $ 前缀；对于数组的元素对象必须使用 $items 替代。当KEY为 * 时表示对所有子表单元素都有效。

表单元素与数据结构的对应关系

一个完整的表单元素我们认为应该包含以下若干元素：

从左至向各元素描述：

一点规范

• 所有 key 按驼峰式命名法

• 若你对 JSON Schema 很熟悉，则忽略 不建议 字样

JSONSchema（SFSchema）

JSON Schema 有完整的对每个属性的规范描述，@yelon/form 当前是基于 draft-07 规范，下列是规范具体说明：

常规类

数值类型

关于exclusiveMinimum和exclusiveMaximum

sf 的实现机制导致无法很好的处理 type 类型的错误捕获，因此默认情况下 sf 是忽略了所有 type （见 config.ts）类型错误，而这两种都错误都会被认为 type 类型错误，从而导致触发无效检查的原因。（更多细节请参考 #676）

字符串类型

数组类型

对象类型

条件类

条件类的校验非常强大和丰富，但是出于会破坏UI导致整个组件构建更复杂，@yelon/form 仅实现 required 的处理，并且把它当成是否显示校验目标，比如：一个登录页，会根据不同登录方式来显示不同登录模式：

schema: SFSchema = {
  properties: {
    type: { type: 'string', enum: [ 'mobile', 'name' ], default: 'mobile' },
    name: { type: 'string' },
    pwd: { type: 'string' },
    mobile: { type: 'string' },
    code: { type: 'string' }
  },
  required: [ 'type' ],
  if: {
    properties: { type: { enum: [ 'mobile' ] } }
  },
  then: {
    required: [ 'mobile', 'code' ]
  },
  else: {
    required: [ 'name', 'pwd' ]
  }
};

上述的最终行为是当登录方式为 mobile 时UI显示 mobile 和 code，反之UI显示 name 和 pwd。

其实条件类最终被解析成 ui.visibleIf，将其转换成如下：

{
  properties: {
    login_type: {
      type: "string",
      title: "登录方式",
      enum: [
        { label: "手机", value: "mobile" },
        { label: "账密", value: "account" }
      ],
      default: "mobile",
      ui: {
        widget: "radio",
        styleType: "button"
      }
    },
    mobile: {
      type: "string",
      ui: {
        visibleIf: {
          login_type: val => val === "mobile"
        }
      }
    },
    code: {
      type: "number",
      ui: {
        visibleIf: {
          login_type: val => val === "mobile"
        }
      }
    },
    name: {
      type: "string",
      ui: {
        visibleIf: {
          login_type: val => val === "account"
        }
      }
    },
    pwd: {
      type: "string",
      ui: {
        type: "password",
        visibleIf: {
          login_type: val => val === "account"
        }
      }
    }
  },
  required: ["login_type"]
};

逻辑类

不建议 主要是并没有对逻辑类进行UI相关处理，它同条件类类似，会影响UI渲染。

格式与视觉类

其他

非标准

UI（SFUISchemaItem）

UI Schema 结构由通用性和小部件API两部分组成，以下是通用性部分进行接口说明，小部件部分自行参数小部件API。

为了小部件的API完整性，小部件Schema说明可能也会包含下列通用性部分。

SFUISchema

等同 <sf [ui]="ui"> 一组与 JSON Schema 结构相对应的 UI 结构体，类型为：[ key: string ]: SFUISchemaItem。

基础类

visibleIf

指定条件时才显示，例如：

• visibleIf: { shown: [ true ] }：当 shown: true 时才显示当前属性

• visibleIf: { shown: [ '$ANY$' ] }：当 shown 包括任意值时

• visibleIf: { shown: (value: any, property: FormProperty) => value > 0 }：复杂表达式

校验类

数组类

表单元素类

渲染类

响应式属性SFGridSchema

grid 属性等同完整的 Grid栅格系统，透过 grid 可以决定表单如何渲染。

水平布局类Schema

务必二者总和为 24