uiSchema 配置

概述

uiSchema 虽然不是必备参数，但是通过它可以增强 FormRender 展示的丰富性
通过 uiSchema 可以覆盖 propSchema 中 type 对应的默认 widget 组件
通过 ui:disabled、ui:readonly、ui:hidden 属性来控制表单项的 UI 展示
通过 ui:options 属性能够实现大量特定的 ui 展示选项

书写规范

uiSchema 里所有的字段都以 ui: 开始，如 ui:widget。
为了满足各用户的使用偏好，uiSchema 可以单独书写，也可以完全归并到 propsSchema，例如：

{
  "propsSchema": {
    "type": "object",
    "properties": {
      "string": {
        "title": "字符串",
        "type": "string"
      }
    }
  },
  "uiSchema": {
    "string": {
      "ui:width": "50%"
    }
  }
}

可以合并为

{
  "propsSchema": {
    "type": "object",
    "properties": {
      "string": {
        "title": "字符串",
        "type": "string",
        "ui:width": "50%"
      }
    }
  }
}

事实上 form-render 内部处理 schema 时第一件事就是将 propsSchema 和 uiSchema 合并，所以上述两种 schema 的渲染效果是一致的。前者适用于遵循 json schema 的团队无缝接入，后者在书写上更为高效。

覆盖 propSchema 中表单项对应的默认 UI Widget

类型	type	默认 widget	其他支持 widget(备注)
布尔值	boolean	checkbox	switch、radio
字符串	string	input	color、date、textarea
数字	number	number	slider
单选项	string/number(带属性 enum)	select	radio
多选	array(带属性 enum)	checkboxes	multiSelect

控制表单项的 UI 展示（共通配置）

ui:disabled: 可控制 input、number、date、checkbox、radio、select、switch 对于组件的 disabled 属性(变灰不可点击)
ui:readonly：可控制 input、number 组件中的 readonly 属性(不可编辑，但不变灰)，列表也支持readonly，效果是列表的控件都会隐藏，导致列表不能增、删和拖拽，进入“只读”模式。但注意列表内的内容还是允许修改的，所以特别要注意如果列表套列表的场景，内部的列表也要 "ui:readonly": true

"someList": {
  "ui:readonly": true
}

ui:hidden：可控制所有基础组件是否显示，可使用 true/false 或表达式，例如：

"age": {
  "ui:hidden": false
}
// 或
"agree": {
  "title": "是否同意",
  "type": "boolean"
},
"personType": {
  "title": "类型",
  "type": "number",
  "enum": [1, 2, 3]
}
...
"age": {
  "ui:hidden": "agree==false && personType!=2"
}

如果使用如上表达式， age 元素将在 agree 元素的值为 false 且 personType 元素不等于 2 时隐藏。注：目前ui:hidden支持==，!=，>和<四种运算符和&&（且），||（或）两种关系符，使用的判断字段（表达式左侧）必须是组件的同级字段。

虽然不推荐，但针对关联组件不在同级的情况，可以使用约定的 formData 关键字寻值：

// 例如 formData 的结构为：
"formData": {
  "x": {
    "y": "abc"
  },
  ...
}
// 注意表达式约定以 "formData." 开头
"xxxx": {
  "ui:hidden": "formData.x.y!='abc'"
}

ui:className：添加组件 root 元素的 className（和 fr-field 这个 className 在同级），用于自定义单独组件的样式
ui:width：单个基础组件的长度，建议使用百分比例如"ui:width":"50%"。

Options

ui:options 里存放特定元素的特定配置。例如textarea的rows

"textareaDemo": {
  "ui:widget": "textarea",
  "ui:options": {
    "rows": 5
  }
}

基本上所有antd文档中组件的 props 都可以使用 ui:options 的方式来直接使用。除此之外我们还提供了一些特别 options：

option	类型	可用组件	说明
foldable	boolean	列表（array）	`{ foldable: true }`用于长列表的收起和展开
hideDelete	boolean	列表（array）	`{ hideDelete: true }`隐藏“删除”按钮

如何编写 uiSchema 设置

{
  "disabledDemo": {
    "ui:disabled": true
  },
  "dateDemo": {
    "ui:widget": "date"
  },
  "objDemo": {
    // 覆盖object里面的元素对应的组件
    "background": {
      "ui:widget": "color"
    }
  },
  "arrDemo": {
    // 数组列表除了默认的新增按钮外，自定义的按钮组（每个按钮点击时会执行对应的callback，使用前请先咨询@侑夕）
    "ui:extraButtons": [
      {
        "text": "Excel导入",
        "icon": "copy",
        "callback": "onCallback1"
      },
      {
        "text": "删除全部",
        "icon": "delete",
        "callback": "clearAll"
      },
      {
        "text": "复制上个",
        "icon": "copy",
        "callback": "copyLast"
      }
    ]
  }
}

5.2 KiB Raw Permalink Blame History Unescape Escape