mirror of
https://github.com/zhigang1992/form-render.git
synced 2026-06-15 18:17:48 +08:00
176 lines
5.2 KiB
Markdown
176 lines
5.2 KiB
Markdown
# uiSchema 配置
|
||
|
||
### 概述
|
||
|
||
- uiSchema 虽然不是必备参数，但是通过它可以增强 FormRender 展示的丰富性
|
||
- 通过 uiSchema 可以覆盖 propSchema 中 type 对应的默认 widget 组件
|
||
- 通过 `ui:disabled`、`ui:readonly`、`ui:hidden` 属性来控制表单项的 UI 展示
|
||
- 通过 `ui:options` 属性能够实现大量特定的 ui 展示选项
|
||
|
||
### 书写规范
|
||
|
||
- uiSchema 里所有的字段都以 `ui:` 开始，如 `ui:widget`。
|
||
- 为了满足各用户的使用偏好，uiSchema 可以单独书写，也可以完全归并到 propsSchema，例如：
|
||
|
||
```json
|
||
{
|
||
"propsSchema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"string": {
|
||
"title": "字符串",
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"uiSchema": {
|
||
"string": {
|
||
"ui:width": "50%"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
可以合并为
|
||
|
||
```json
|
||
{
|
||
"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
|
||
|
||
```js
|
||
"someList": {
|
||
"ui:readonly": true
|
||
}
|
||
```
|
||
|
||
- `ui:hidden`：可控制所有基础组件是否显示，可使用 true/false 或表达式，例如：
|
||
|
||
```json
|
||
"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` 关键字寻值：
|
||
|
||
```json
|
||
// 例如 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`
|
||
|
||
```json
|
||
"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 设置
|
||
|
||
```json
|
||
{
|
||
"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"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|