36 KiB
Executable File
title | description | type | group | menuName | icon | order |
---|---|---|---|---|---|---|
Combo 组合 | 0 | null | Combo | 12 |
用于将多个表单项组合到一起,实现深层结构的数据编辑。
比如想提交 user.name
这样的数据结构,有两种方法:一种是将表单项的 name 设置为user.name
,另一种就是使用 combo。
基本使用
配置items
属性,组合多个表单项
{
"type": "form",
"debug": true,
"api": "/api/mock2/form/saveForm",
"body": [
{
"type": "combo",
"name": "user",
"label": "用户",
"items": [
{
"name": "text",
"label": "名字",
"type": "input-text"
},
{
"name": "gender",
"label": "性别",
"type": "select",
"options": ["男", "女"]
}
]
}
]
}
多行展示模式
默认,combo 内表单项是横着展示一排,如果想换行展示,可以配置"multiLine": true
{
"type": "form",
"mode": "horizontal",
"api": "/api/mock2/form/saveForm",
"body": [
{
"type": "combo",
"name": "combo1",
"label": "Combo 单行展示",
"items": [
{
"name": "text",
"label": "文本",
"type": "input-text"
},
{
"name": "select",
"label": "选项",
"type": "select",
"options": ["a", "b", "c"]
}
]
},
{
"type": "divider"
},
{
"type": "combo",
"name": "combo2",
"label": "Combo 多行展示",
"multiLine": true,
"items": [
{
"name": "text",
"label": "文本",
"type": "input-text"
},
{
"name": "select",
"label": "选项",
"type": "select",
"options": ["a", "b", "c"]
}
]
}
]
}
多选模式
默认,combo 为单选模式,可以配置"multiple": true
实现多选模式。
这时提交的将会是对象数组。
{
"type": "form",
"mode": "horizontal",
"api": "/api/mock2/form/saveForm",
"debug": true,
"body": [
{
"type": "combo",
"name": "combo1",
"label": "Combo 单选展示",
"items": [
{
"name": "text",
"label": "文本",
"type": "input-text"
},
{
"name": "select",
"label": "选项",
"type": "select",
"options": ["a", "b", "c"]
}
]
},
{
"type": "divider"
},
{
"type": "combo",
"name": "combo2",
"label": "Combo 多选展示",
"multiple": true,
"items": [
{
"name": "text",
"label": "文本",
"type": "input-text"
},
{
"name": "select",
"label": "选项",
"type": "select",
"options": ["a", "b", "c"]
}
]
}
]
}
限制个数
多选模式下,可以配置minLength
和maxLength
配置该 Combo 可添加的条数
{
"type": "form",
"mode": "horizontal",
"api": "/api/mock2/form/saveForm",
"body": [
{
"type": "combo",
"name": "combo1",
"label": "最少添加1条",
"multiple": true,
"minLength": 1,
"items": [
{
"name": "text",
"label": "文本",
"type": "input-text"
},
{
"name": "select",
"label": "选项",
"type": "select",
"options": ["a", "b", "c"]
}
]
},
{
"type": "combo",
"name": "combo2",
"label": "最多添加3条",
"multiple": true,
"maxLength": 3,
"items": [
{
"name": "text",
"label": "文本",
"type": "input-text"
},
{
"name": "select",
"label": "选项",
"type": "select",
"options": ["a", "b", "c"]
}
]
}
]
}
也可以使用变量配置minLength
和maxLength
2.4.1 及以上版本
{
"type": "form",
"mode": "horizontal",
"api": "/api/mock2/form/saveForm",
"data": {
"minLength": 2,
"maxLength": 4
},
"body": [
{
"type": "combo",
"name": "combo1",
"label": "最少添加2条, 最多添加4条",
"mode": "normal",
"multiple": true,
"minLength": "${minLength}",
"maxLength": "${maxLength}",
"items": [
{
"name": "text",
"label": "文本",
"type": "input-text"
},
{
"name": "select",
"label": "选项",
"type": "select",
"options": ["a", "b", "c"]
}
]
}
]
}
值格式
观察下例中表单数据域值的变化,可以发现:
- 单选模式时,数据格式为对象;
- 多选模式时,数据格式为数组,数组成员是对象
{
"type": "form",
"debug": true,
"mode": "horizontal",
"api": "/api/mock2/form/saveForm",
"body": [
{
"type": "combo",
"name": "combo1",
"label": "Combo 单选展示",
"items": [
{
"name": "text",
"label": "文本",
"type": "input-text"
},
{
"name": "select",
"label": "选项",
"type": "select",
"options": ["a", "b", "c"]
}
]
},
{
"type": "divider"
},
{
"type": "combo",
"name": "combo2",
"label": "Combo 多选展示",
"multiple": true,
"items": [
{
"name": "text",
"label": "文本",
"type": "input-text"
},
{
"name": "select",
"label": "选项",
"type": "select",
"options": ["a", "b", "c"]
}
]
}
]
}
打平值
默认多选模式下,数据格式是对象数组的形式,当你配置的组合中只有一个表单项时,可以配置"flat": true
,将值进行打平处理。
{
"type": "form",
"debug": true,
"mode": "horizontal",
"api": "/api/mock2/form/saveForm",
"body": [
{
"type": "combo",
"name": "combo1",
"label": "默认模式",
"multiple": true,
"items": [
{
"name": "text",
"type": "input-text"
}
]
},
{
"type": "divider"
},
{
"type": "combo",
"name": "combo2",
"label": "打平模式",
"multiple": true,
"flat": true,
"items": [
{
"name": "text",
"type": "input-text"
}
]
}
]
}
查看上例表单数据域,可以看到打平后数据格式如下:
{
"combo2": ["aaa", "bbb"]
}
增加层级
combo 还有一个作用是增加层级,比如返回的数据是一个深层对象
{
"a": {
"b": "data"
}
}
如果要用文本框显示,name 必须是 a.b
,但使用 combo 创建层级后,name 就可以只是 b
:
{
"name": "a",
"type": "combo",
"label": "",
"noBorder": true,
"multiLine": true,
"items": [
{
"type": "input-text",
"name": "b"
}
]
}
这样就能结合 definitions 实现无限层级结构。
唯一验证
可以在配置的body
项上,配置"unique": true
,指定当前表单项不可重复
{
"type": "form",
"debug": true,
"mode": "horizontal",
"api": "/api/mock2/form/saveForm",
"body": [
{
"type": "combo",
"name": "combo666",
"label": "唯一",
"multiple": true,
"items": [
{
"name": "text",
"type": "input-text",
"placeholder": "文本",
"unique": true
},
{
"name": "select",
"type": "select",
"options": [
"a",
"b",
"c"
],
"unique": true
}
]
}
]
}
上例中,text
和select
都配置了"unique": true
,新增多条 combo,在任意两个text
输入框的值相同时,提交时都会报错"当前值不唯一"
,而select
选择框也不可选择重复的选项
暂不支持
Nested-Select
组件
拖拽排序
多选模式下,可以配置"draggable": true
实现拖拽调整排序
{
"type": "form",
"debug": true,
"mode": "horizontal",
"api": "/api/mock2/form/saveForm",
"body": [
{
"type": "combo",
"name": "combo",
"label": "拖拽排序",
"multiple": true,
"value": [
{
"text": "1",
"select": "a"
},
{
"text": "2",
"select": "b"
}
],
"draggable": true,
"items": [
{
"name": "text",
"type": "input-text"
},
{
"name": "select",
"type": "select",
"options": [
"a",
"b",
"c"
]
}
]
}
]
}
条件分支
默认 Combo 渲染的成员是固定表单项的,成员的类型时一致,如果不一致怎么办?这里可以设置条件分支来给不同的成员设置不同的表单项。
如下面的例子,定义了两种类型:文本和数字,用户新增的时候可以选择是新增文本还是数字。区分是文字和数字的方式是根据成员数据中的 type 字段来决定。
{
"type": "combo",
"name": "combo-conditions2",
"label": "多选",
"value": [
{
"type": "text"
}
],
"multiLine": true,
"multiple": true,
"typeSwitchable": false,
"conditions": [
{
"label": "文本",
"test": "this.type === \"text\"",
"scaffold": {
"type": "text",
"label": "文本",
"name": ""
},
"items": [
{
"label": "名称",
"name": "label",
"type": "input-text"
},
{
"label": "字段名",
"name": "name",
"type": "input-text"
}
]
},
{
"label": "数字",
"test": "this.type === \"number\"",
"scaffold": {
"type": "number",
"label": "数字",
"name": ""
},
"items": [
{
"label": "名称",
"name": "label",
"type": "input-text"
},
{
"label": "字段名",
"name": "name",
"type": "input-text"
},
{
"label": "最小值",
"name": "min",
"type": "input-number"
},
{
"label": "最大值",
"name": "max",
"type": "input-number"
},
{
"label": "步长",
"name": "step",
"type": "input-number"
}
]
}
]
}
conditions
Array 数组,每个成员是一种类型conditions[x].label
类型名称conditions[x].test
表达式,目标成员数据是否属于这个类型?conditions[x].scaffold
初始数据,当新增的时候直接使用此数据。conditions[x].items
该类型的表单设置。typeSwitchable
类型是否允许切换,如果设置成 true 会多一个类型切换的按钮。
Tabs 模式
默认成员是一个一个排列的,如果数据比较多有点让人眼花缭乱。所以 Combo 支持了 tabs 的排列方式。
{
"type": "combo",
"name": "combo101",
"label": "组合多条多行",
"multiple": true,
"multiLine": true,
"value": [
{}
],
"tabsMode": true,
"tabsStyle": "card",
"maxLength": 3,
"items": [
{
"name": "a",
"label": "文本",
"type": "input-text",
"placeholder": "文本",
"value": "",
"size": "full"
},
{
"name": "b",
"label": "选项",
"type": "select",
"options": [
"a",
"b",
"c"
],
"size": "full"
}
]
}
tabsMode
boolean 用来开启此模式tabsStyle
string 样式,可选:line
、card
或者radio
.tabsLabelTpl
用来生成标题的模板,默认为:成员 ${index|plus}
注意:这是新引入的功能,目前还不支持拖拽组合使用。且此模式只有多选时才能生效。
获取父级数据
默认情况下,Combo 内表达项无法获取父级数据域的数据,如下,我们添加 Combo 表单项时,尽管 Combo 内的文本框的name
与父级数据域中的super_text
变量同名,但是没有自动映射值。
{
"type": "form",
"debug": true,
"mode": "horizontal",
"api": "/api/mock2/form/saveForm",
"body": [
{
"type": "input-text",
"label": "父级文本框",
"name": "super_text",
"value": "123"
},
{
"type": "combo",
"name": "combo1",
"label": "不可获取父级数据",
"multiple": true,
"items": [
{
"name": "super_text",
"type": "input-text"
}
]
}
]
}
可以配置"canAccessSuperData": true
开启此特性,如下,配置了该配置项后,添加 Combo 的text
表单项会自动映射父级数据域的同名变量
{
"type": "form",
"debug": true,
"mode": "horizontal",
"api": "/api/mock2/form/saveForm",
"body": [
{
"type": "input-text",
"label": "父级文本框",
"name": "super_text",
"value": "123"
},
{
"type": "combo",
"name": "combo2",
"label": "可获取父级数据",
"multiple": true,
"canAccessSuperData": true,
"items": [
{
"name": "super_text",
"type": "input-text"
}
]
}
]
}
同步更新内部表单项
配置canAccessSuperData
可以获取父级数据域值,但是为了效率,在父级数据域变化的时候,默认 combo 内部是不会进行同步的
如下,添加一组 combo,然后可以看到默认会映射父级变量值123
,但是当你在更改父级数据域super_text
文本框值后,combo 内部文本框并没有同步更新
{
"type": "form",
"debug": true,
"mode": "horizontal",
"api": "/api/mock2/form/saveForm",
"body": [
{
"type": "input-text",
"label": "父级文本框",
"name": "super_text",
"value": "123"
},
{
"type": "combo",
"name": "combo2",
"label": "可获取父级数据",
"multiple": true,
"canAccessSuperData": true,
"items": [
{
"name": "super_text",
"type": "input-text"
}
]
}
]
}
如果想实现内部同步更新,需要如下配置:
- 配置
"strictMode": false
- 配置
syncFields
字符串数组,数组项是需要同步的变量名
以上面为例,我们在 combo 上配置"strictMode": false
和"syncFields": ["super_text"]
,即可实现同步
{
"type": "form",
"debug": true,
"mode": "horizontal",
"api": "/api/mock2/form/saveForm",
"body": [
{
"type": "input-text",
"label": "父级文本框",
"name": "super_text",
"value": "123"
},
{
"type": "combo",
"name": "combo2",
"label": "可获取父级数据",
"multiple": true,
"canAccessSuperData": true,
"strictMode": false,
"syncFields": ["super_text"],
"items": [
{
"name": "super_text",
"type": "input-text"
}
]
}
]
}
设置序号
默认 Combo 数据域中,每一项会有一个隐藏变量index
,可以利用 Tpl 组件,显示当前项序号
{
"type": "form",
"debug": true,
"mode": "horizontal",
"api": "/api/mock2/form/saveForm",
"body": [
{
"type": "combo",
"name": "combo",
"label": "显示序号",
"multiple": true,
"items": [
{
"type": "tpl",
"tpl": "<%= this.index + 1%>",
"className": "p-t-xs",
"mode": "inline"
},
{
"name": "text",
"type": "input-text"
}
]
}
]
}
自定义删除按钮
默认删除单项按钮为"x",可以通过配置 deleteBtn 属性自定义删除单项按钮,目前 deleteBtn 支持的属性有
string
和Button类型
如下,当 deleteBtn 为string
时,对应的值会被渲染成文本
{
"type": "form",
"debug": true,
"mode": "horizontal",
"api": "/api/mock2/form/saveForm",
"body": [
{
"type": "combo",
"name": "combo",
"label": "删除按钮文本",
"multiple": true,
"deleteBtn": "删除",
"items": [
{
"name": "text",
"type": "input-text"
}
],
"value": [
{
"text": "1"
}
]
}
]
}
如果想要赋予删除按钮更多能力,则需要将 deleteBtn 配置成Button类型
{
"type": "form",
"debug": true,
"mode": "horizontal",
"api": "/api/mock2/form/saveForm",
"body": [
{
"type": "combo",
"name": "combo",
"label": "更复杂的删除按钮",
"multiple": true,
"deleteBtn": {
"type": "button",
"label": "delete",
"level": "danger",
"tooltip": "提示文本",
"tooltipPlacement": "top",
"onClick": "alert(index)"
},
"items": [
{
"name": "text",
"type": "input-text"
}
],
"value": [
{
"text": "1"
}
]
}
]
}
自定义新增按钮
可以通过配置 addBtn
属性自定义新增按钮,在非 Tabs 模式下生效。目前 addBtn
支持属性 Button类型
如果仅想更改新增按钮文本请使用 addButtonText
, 仅想增添样式请使用 addButtonClassName
{
"type": "form",
"debug": true,
"mode": "horizontal",
"api": "/api/mock2/form/saveForm",
"body": [
{
"type": "combo",
"name": "combo",
"label": "自定义新增",
"multiple": true,
"addBtn": {
"type": "button",
"label": "增加",
"level": "default",
"block": true
},
"items": [
{
"name": "text",
"type": "input-text"
}
],
"value": [
{
"text": ""
}
]
}
]
}
属性表
当做选择器表单项使用时,除了支持 普通表单项属性表 中的配置以外,还支持下面一些配置
属性名 | 类型 | 默认值 | 说明 |
---|---|---|---|
formClassName | string |
单组表单项的类名 | |
items | Array<表单项> | 组合展示的表单项 | |
items[x].columnClassName | string |
列的类名,可以用它配置列宽度。默认平均分配。 | |
items[x].unique | boolean |
设置当前列值是否唯一,即不允许重复选择。 | |
noBorder | boolean |
false |
单组表单项是否显示边框 |
scaffold | object |
{} |
单组表单项初始值 |
multiple | boolean |
false |
是否多选 |
multiLine | boolean |
false |
默认是横着展示一排,设置以后竖着展示 |
minLength | number |
最少添加的条数,2.4.1 版本后支持变量 |
|
maxLength | number |
最多添加的条数,2.4.1 版本后支持变量 |
|
flat | boolean |
false |
是否将结果扁平化(去掉 name),只有当 items 的 length 为 1 且 multiple 为 true 的时候才有效。 |
joinValues | boolean |
true |
默认为 true 当扁平化开启的时候,是否用分隔符的形式发送给后端,否则采用 array 的方式。 |
delimiter | string |
false |
当扁平化开启并且 joinValues 为 true 时,用什么分隔符。 |
addable | boolean |
false |
是否可新增 |
addattop | boolean |
false |
在顶部添加 |
removable | boolean |
false |
是否可删除 |
deleteApi | API | 如果配置了,则删除前会发送一个 api,请求成功才完成删除 | |
deleteConfirmText | string |
"确认要删除?" |
当配置 deleteApi 才生效!删除时用来做用户确认 |
draggable | boolean |
false |
是否可以拖动排序, 需要注意的是当启用拖动排序的时候,会多一个$id 字段 |
draggableTip | string |
可拖拽的提示文字 | |
subFormMode | string |
"normal" |
可选normal 、horizontal 、inline |
subFormHorizontal | Object |
{"left":2, "right":10, justify: false} |
当 subFormMode 为 horizontal 时有用,用来控制 label 的展示占比 |
placeholder | string |
`` | 没有成员时显示。 |
canAccessSuperData | boolean |
false |
指定是否可以自动获取上层的数据并映射到表单项上 |
conditions | object |
数组的形式包含所有条件的渲染类型,单个数组内的test 为判断条件,数组内的items 为符合该条件后渲染的schema |
|
typeSwitchable | boolean |
false |
是否可切换条件,配合conditions 使用 |
strictMode | boolean |
true |
默认为严格模式,设置为 false 时,当其他表单项更新是,里面的表单项也可以及时获取,否则不会。 |
syncFields | Array<string> |
[] |
配置同步字段。只有 strictMode 为 false 时有效。如果 Combo 层级比较深,底层的获取外层的数据可能不同步。但是给 combo 配置这个属性就能同步下来。输入格式:["os"] |
nullable | boolean |
false |
允许为空,如果子表单项里面配置验证器,且又是单条模式。可以允许用户选择清空(不填)。 |
itemClassName | string |
单组 CSS 类 | |
itemsWrapperClassName | string |
组合区域 CSS 类 | |
deleteBtn | Button or string |
自定义删除按钮 | 只有当removable 为 true 时有效; 如果为string 则为按钮的文本;如果为Button 则根据配置渲染删除按钮。 |
addBtn | Button | 自定义新增按钮 | 可新增自定义配置渲染新增按钮,在tabsMode: true 下不生效。 |
addButtonClassName | string |
新增按钮 CSS 类名 | |
addButtonText | string |
"新增" |
新增按钮文字 |
事件表
当前组件会对外派发以下事件,可以通过onEvent
来监听这些事件,并通过actions
来配置执行的动作,在actions
中可以通过${事件参数名}
来获取事件产生的数据(< 2.3.2 及以下版本 为 ${event.data.[事件参数名]}
),详细请查看事件动作。
[name]
表示当前组件绑定的名称,即name
属性,如果没有配置name
属性,则通过value
取值。
事件名称 | 事件参数 | 说明 |
---|---|---|
add | [name]: object | object[] 组件的值 |
添加组合项时触发 |
delete | key: number 移除项的索引item: object 移除项[name]: object | object[] 组件的值 |
删除组合项时触发 |
tabsChange | key: number 选项卡索引item: object 激活项[name]: object | object[] 组件的值 |
当设置 tabsMode 为 true 时,切换选项卡时触发 |
动作表
当前组件对外暴露以下特性动作,其他组件可以通过指定actionType: 动作名称
、componentId: 该组件id
来触发这些动作,动作配置可以通过args: {动作配置项名称: xxx}
来配置具体的参数,详细请查看事件动作。
动作名称 | 动作配置 | 说明 |
---|---|---|
addItem | item: object 新增项的值 |
只有开启multiple 模式才能使用, multiple 模式下,给新增项添加默认值 |
clear | - | 清空 |
reset | - | 将值重置为resetValue ,若没有配置resetValue ,则清空 |
setValue | value: object | Array<object> 更新的值index?: number 指定更新的数据索引, 1.10.1 及以上版本引入 |
更新数据,对象数组针对开启multiple 模式, multiple 模式下可以通过指定index 来更新指定索引的数据 |
动作示例
复制数值
1.10.1 及以上版本
此示例主要用来演示如何通过已有数据快速填充 combo 某条数据。点击 copy 按钮会弹出一个 crud 列表,点击对应行上的复制按钮,将选中数据填充到外层的 combo.
注意事项:
- 需要给 combo 设置个 id 属性,用来给事件动作指定目标用。
- 弹窗按钮配置了数据映射
{comboIndex: "${index}"}
因为 crud 的行数据上也有 index 变量,派送动作时获取 index 变量是 crud 所在行的序号。所以弹出弹窗的时候,先把 combo 的序号赋值给 comboIndex - crud 操作栏里面添加了个按钮,close: true 设置是让动作完成后关闭弹窗。
- 按钮里面添加了 onEvent 配置,click 时做
setValue
动作,并设置参数 index 为 '${comboIndex}' 值为${&}
。其中${&}
是特殊语法,用来取整个上下数据。
{
"type": "form",
"mode": "horizontal",
"api": "/api/mock2/form/saveForm",
"body": [
{
"type": "combo",
"name": "combo",
"id": "thecombo",
"multiple": true,
"value": [
{
"engine": ""
}
],
"items": [
{
"name": "engine",
"type": "input-text"
},
{
"label": "Copy",
"type": "button",
"actionType": "dialog",
"size": "md",
"dialog": {
"title": "历史记录",
"actions": [],
"data": {
"comboIndex": "${index}"
},
"body": [
{
"type": "crud",
"api": "/api/mock2/sample",
"columns": [
{
"label": "Engine",
"name": "engine"
},
{
"type": "operation",
"label": "操作",
"buttons": [
{
"label": "复制",
"type": "button",
"close": true,
"onEvent": {
"click": {
"actions": [
{
"componentId": "thecombo",
"actionType": "setValue",
"args": {
"index": "${comboIndex}",
"value": "${&}"
}
}
]
}
}
}
]
}
]
}
]
}
}
]
}
]
}