mirror of
https://gitee.com/baidu/amis.git
synced 2024-12-15 09:21:13 +08:00
45 KiB
Executable File
45 KiB
Executable File
| title | description | type | group | menuName | icon | order |
|---|---|---|---|---|---|---|
| Select 选择器 | 0 | null | Select 选择器 | 48 |
基本用法
参考 Options
自定义菜单
{
"type": "form",
"body": [
{
"label": "选项",
"type": "select",
"name": "select",
"menuTpl": "<div>${label} 值：${value}, 当前是否选中: ${checked}</div>",
"options": [
{
"label":"A",
"value":"a"
},
{
"label":"B",
"value":"b"
},
{
"label":"C",
"value":"c"
}
]
}
]
}
分组展示模式
单选
{
"type": "form",
"api": "/api/mock2/form/saveForm",
"body": [
{
"label": "分组",
"type": "select",
"name": "a",
"selectMode": "group",
"options": [
{
"label": "法师",
"children": [
{
"label": "诸葛亮",
"value": "zhugeliang"
}
]
},
{
"label": "战士",
"children": [
{
"label": "曹操",
"value": "caocao"
},
{
"label": "钟无艳",
"value": "zhongwuyan"
}
]
},
{
"label": "打野",
"children": [
{
"label": "李白",
"value": "libai"
},
{
"label": "韩信",
"value": "hanxin"
},
{
"label": "云中君",
"value": "yunzhongjun"
}
]
}
]
}
]
}
多选
{
"type": "form",
"api": "/api/mock2/form/saveForm",
"body": [
{
"label": "分组",
"type": "select",
"name": "a",
"multiple": true,
"selectMode": "group",
"options": [
{
"label": "法师",
"children": [
{
"label": "诸葛亮",
"value": "zhugeliang"
}
]
},
{
"label": "战士",
"children": [
{
"label": "曹操",
"value": "caocao"
},
{
"label": "钟无艳",
"value": "zhongwuyan"
}
]
},
{
"label": "打野",
"children": [
{
"label": "李白",
"value": "libai"
},
{
"label": "韩信",
"value": "hanxin"
},
{
"label": "云中君",
"value": "yunzhongjun"
}
]
}
]
}
]
}
表格模式
需要额外配置 columns 配置，参考 Table 中的说明。
单选
{
"type": "form",
"api": "/api/mock2/form/saveForm",
"body": [
{
"label": "表格形式",
"type": "select",
"name": "a",
"selectMode": "table",
"columns": [
{
"name": "label",
"label": "英雄"
},
{
"name": "position",
"label": "位置"
}
],
"options": [
{
"label": "诸葛亮",
"value": "zhugeliang",
"position": "中单"
},
{
"label": "曹操",
"value": "caocao",
"position": "上单"
},
{
"label": "钟无艳",
"value": "zhongwuyan",
"position": "上单"
},
{
"label": "李白",
"value": "libai",
"position": "打野"
},
{
"label": "韩信",
"value": "hanxin",
"position": "打野"
},
{
"label": "云中君",
"value": "yunzhongjun",
"position": "打野"
}
]
}
]
}
多选
{
"type": "form",
"api": "/api/mock2/form/saveForm",
"body": [
{
"label": "表格形式",
"type": "select",
"name": "a",
"selectMode": "table",
"multiple": true,
"columns": [
{
"name": "label",
"label": "英雄"
},
{
"name": "position",
"label": "位置"
}
],
"options": [
{
"label": "诸葛亮",
"value": "zhugeliang",
"position": "中单"
},
{
"label": "曹操",
"value": "caocao",
"position": "上单"
},
{
"label": "钟无艳",
"value": "zhongwuyan",
"position": "上单"
},
{
"label": "李白",
"value": "libai",
"position": "打野"
},
{
"label": "韩信",
"value": "hanxin",
"position": "打野"
},
{
"label": "云中君",
"value": "yunzhongjun",
"position": "打野"
}
]
}
]
}
树形模式
单选
{
"type": "form",
"api": "/api/mock2/form/saveForm",
"body": [
{
"label": "树型展示",
"type": "select",
"name": "a",
"selectMode": "tree",
"options": [
{
"label": "法师",
"children": [
{
"label": "诸葛亮",
"value": "zhugeliang"
}
]
},
{
"label": "战士",
"children": [
{
"label": "曹操",
"value": "caocao"
},
{
"label": "钟无艳",
"value": "zhongwuyan"
}
]
},
{
"label": "打野",
"children": [
{
"label": "李白",
"value": "libai"
},
{
"label": "韩信",
"value": "hanxin"
},
{
"label": "云中君",
"value": "yunzhongjun"
}
]
}
]
}
]
}
多选
{
"type": "form",
"api": "/api/mock2/form/saveForm",
"body": [
{
"label": "树型展示",
"type": "select",
"name": "a",
"multiple": true,
"selectMode": "tree",
"options": [
{
"label": "法师",
"children": [
{
"label": "诸葛亮",
"value": "zhugeliang"
}
]
},
{
"label": "战士",
"children": [
{
"label": "曹操",
"value": "caocao"
},
{
"label": "钟无艳",
"value": "zhongwuyan"
}
]
},
{
"label": "打野",
"children": [
{
"label": "李白",
"value": "libai"
},
{
"label": "韩信",
"value": "hanxin"
},
{
"label": "云中君",
"value": "yunzhongjun"
}
]
}
]
}
]
}
级联选择
按列来点选。
单选
{
"type": "form",
"api": "/api/mock2/form/saveForm",
"body": [
{
"label": "级联选择",
"type": "select",
"name": "a",
"selectMode": "chained",
"options": [
{
"label": "法师",
"children": [
{
"label": "诸葛亮",
"value": "zhugeliang"
}
]
},
{
"label": "战士",
"children": [
{
"label": "曹操",
"value": "caocao"
},
{
"label": "钟无艳",
"value": "zhongwuyan"
}
]
},
{
"label": "打野",
"children": [
{
"label": "李白",
"value": "libai"
},
{
"label": "韩信",
"value": "hanxin"
},
{
"label": "云中君",
"value": "yunzhongjun"
}
]
}
]
}
]
}
多选
{
"type": "form",
"api": "/api/mock2/form/saveForm",
"body": [
{
"label": "级联选择",
"type": "select",
"name": "a",
"selectMode": "chained",
"multiple": true,
"options": [
{
"label": "法师",
"children": [
{
"label": "诸葛亮",
"value": "zhugeliang"
}
]
},
{
"label": "战士",
"children": [
{
"label": "曹操",
"value": "caocao"
},
{
"label": "钟无艳",
"value": "zhongwuyan"
}
]
},
{
"label": "打野",
"children": [
{
"label": "李白",
"value": "libai"
},
{
"label": "韩信",
"value": "hanxin"
},
{
"label": "云中君",
"value": "yunzhongjun"
}
]
}
]
}
]
}
支持搜索
{
"type": "form",
"api": "/api/mock2/form/saveForm",
"body": [
{
"label": "带搜索",
"type": "select",
"name": "a",
"selectMode": "chained",
"searchable": true,
"sortable": true,
"multiple": true,
"options": [
{
"label": "法师",
"children": [
{
"label": "诸葛亮",
"value": "zhugeliang"
}
]
},
{
"label": "战士",
"children": [
{
"label": "曹操",
"value": "caocao"
},
{
"label": "钟无艳",
"value": "zhongwuyan"
}
]
},
{
"label": "打野",
"children": [
{
"label": "李白",
"value": "libai"
},
{
"label": "韩信",
"value": "hanxin"
},
{
"label": "云中君",
"value": "yunzhongjun"
}
]
}
]
}
]
}
自定义搜索函数
默认通过match-sorter搜索过滤 value,label 中的值
可通过filterOption自定义搜索过滤函数
{
"type": "form",
"api": "/api/mock2/form/saveForm",
"body": [
{
"label": "带搜索",
"type": "select",
"name": "a",
"selectMode": "chained",
"searchable": true,
"filterOption": "return options.filter(({value, label, weapon}) => value?.includes(inputValue) || label?.includes(inputValue) || weapon?.includes(inputValue));",
"sortable": true,
"multiple": true,
"options": [
{
"label": "诸葛亮",
"value": "zhugeliang",
"weapon": "翡翠仙扇"
},
{
"label": "曹操",
"value": "caocao",
"weapon": "幻影双刃"
},
{
"label": "钟无艳",
"value": "zhongwuyan",
"weapon": "破岳震天锤"
},
{
"label": "李白",
"value": "libai",
"weapon": "青丝缠月剑"
},
{
"label": "韩信",
"value": "hanxin",
"weapon": "龙吟穿云枪"
},
{
"label": "云中君",
"value": "yunzhongjun",
"weapon": "飘渺云影剑"
}
]
}
]
}
延时加载
选型设置 defer: true，结合配置组件层的 deferApi 来实现。
{
"type": "form",
"api": "/api/mock2/form/saveForm",
"body": [
{
"label": "延时加载",
"type": "select",
"name": "a",
"multiple": true,
"selectMode": "tree",
"deferApi": "/api/mock2/form/deferOptions?label=${label}&waitSeconds=2",
"options": [
{
"label": "法师",
"children": [
{
"label": "诸葛亮",
"value": "zhugeliang"
}
]
},
{
"label": "战士",
"defer": true
},
{
"label": "打野",
"children": [
{
"label": "李白",
"value": "libai"
},
{
"label": "韩信",
"value": "hanxin"
},
{
"label": "云中君",
"value": "yunzhongjun"
}
]
}
]
}
]
}
关联选择模式
分为左右两部分，左边点选后关联出现右边。左右都可以配置展示模式。
单选
{
"type": "form",
"api": "/api/mock2/form/saveForm",
"body": [
{
"label": "关联选择模式",
"type": "select",
"name": "b",
"sortable": true,
"searchable": true,
"deferApi": "/api/mock2/form/deferOptions?label=${label}",
"selectMode": "associated",
"leftMode": "tree",
"leftOptions": [
{
"label": "法师",
"children": [
{
"label": "诸葛亮",
"value": "zhugeliang"
}
]
},
{
"label": "战士",
"children": [
{
"label": "曹操",
"value": "caocao"
},
{
"label": "钟无艳",
"value": "zhongwuyan"
}
]
},
{
"label": "打野",
"children": [
{
"label": "李白",
"value": "libai"
},
{
"label": "韩信",
"value": "hanxin"
},
{
"label": "云中君",
"value": "yunzhongjun"
}
]
}
],
"options": [
{
"ref": "zhugeliang",
"children": [
{
"label": "A",
"value": "a"
}
]
},
{
"ref": "caocao",
"children": [
{
"label": "B",
"value": "b"
},
{
"label": "C",
"value": "c"
}
]
},
{
"ref": "zhongwuyan",
"children": [
{
"label": "D",
"value": "d"
},
{
"label": "E",
"value": "e"
}
]
},
{
"ref": "libai",
"defer": true
},
{
"ref": "hanxin",
"defer": true
},
{
"ref": "yunzhongjun",
"defer": true
}
]
}
]
}
多选
{
"type": "form",
"api": "/api/mock2/form/saveForm",
"body": [
{
"label": "关联选择模式",
"type": "select",
"name": "b",
"multiple": true,
"sortable": true,
"searchable": true,
"deferApi": "/api/mock2/form/deferOptions?label=${label}",
"selectMode": "associated",
"leftMode": "tree",
"leftOptions": [
{
"label": "法师",
"children": [
{
"label": "诸葛亮",
"value": "zhugeliang"
}
]
},
{
"label": "战士",
"children": [
{
"label": "曹操",
"value": "caocao"
},
{
"label": "钟无艳",
"value": "zhongwuyan"
}
]
},
{
"label": "打野",
"children": [
{
"label": "李白",
"value": "libai"
},
{
"label": "韩信",
"value": "hanxin"
},
{
"label": "云中君",
"value": "yunzhongjun"
}
]
}
],
"options": [
{
"ref": "zhugeliang",
"children": [
{
"label": "A",
"value": "a"
}
]
},
{
"ref": "caocao",
"children": [
{
"label": "B",
"value": "b"
},
{
"label": "C",
"value": "c"
}
]
},
{
"ref": "zhongwuyan",
"children": [
{
"label": "D",
"value": "d"
},
{
"label": "E",
"value": "e"
}
]
},
{
"ref": "libai",
"defer": true
},
{
"ref": "hanxin",
"defer": true
},
{
"ref": "yunzhongjun",
"defer": true
}
]
}
]
}
leftOptions 动态加载，默认 source 接口是返回 options 部分，而 leftOptions 是没有对应的接口可以动态返回了。为了方便，目前如果 source 接口返回的选中中，第一个 option 是以下这种格式则也会把 options[0].leftOptions 当成 leftOptions, options[0].children 当 options。同时 options[0].leftDefaultValue 可以用来配置左侧选项的默认值。
{
status: 0,
msg: '',
data: {
options: [
{
leftOptions: [],
children: [],
leftDefaultValue: ''
}
]
}
}
人员点选
请通过网络面板查看接口请求返回。
实际上就是采用的「关联选择模式」的 select，注意要看那一部分文档，需要知道怎么动态加载 leftOptions。左侧部分和人员都是通过 source 接口返回。需要懒加载的项通过设置 defer 为 true 来标记。左右两部分都支持懒加载。
都是通过 deferApi 来实现，后端根据传过来的参数决定是懒加载树，还是栏加载人员。
- 有 dep 值则是懒加载部门树
- 有 ref 值则是懒加载人员
{
"type": "form",
"api": "/api/mock2/form/saveForm",
"body": [
{
"label": "人员选择",
"type": "select",
"name": "b",
"multiple": true,
"sortable": true,
"searchable": true,
"selectMode": "associated",
"leftMode": "tree",
"source": "/api/mock2/form/departUser",
"searchApi": '/api/mock2/form/departUserSearch?term=${term}',
"deferApi": "/api/mock2/form/departUser?ref=${ref}&dep=${value}"
}
]
}
限制标签最大展示数量
1.10.0 及以上版本
maxTagCount可以限制标签的最大展示数量，超出数量的部分会收纳到 Popover 中，可以通过overflowTagPopover配置 Popover 相关的属性，注意该属性仅在多选模式开启后生效。
{
"type": "form",
"api": "/api/mock2/form/saveForm",
"body": [
{
"label": "水果",
"type": "select",
"name": "select",
"multiple": true,
"maxTagCount": 3,
"checkAll": true,
"defaultCheckAll": true,
"overflowTagPopover": {
"title": "水果"
},
"options": [
{"label": "苹果", "value": "Apple"},
{"label": "香蕉", "value": "Banana"},
{"label": "黑莓", "value": "Blackberry"},
{"label": "蓝莓", "value": "Blueberry"},
{"label": "樱桃", "value": "Cherry"},
{"label": "杨桃", "value": "Carambola"},
{"label": "椰子", "value": "Coconut"},
{"label": "猕猴桃", "value": "Kiwifruit"},
{"label": "柠檬", "value": "Lemon"},
{"label": "菠萝", "value": "Pineapple"}
]
}
]
}
自定义下拉区域宽度与对齐方式
2.8.0 以上版本
使用字符串或数字，使用数字时单位为px；支持单位: %、px、rem、em、vw。
{
"type": "page",
"body": {
"type": "form",
"body": [
{
"label": "80% 宽度靠右对齐",
"type": "select",
"name": "select",
"menuTpl": "<div>${label} 值：${value}, 当前是否选中: ${checked}</div>",
"overlay": {
"width": "80%",
"align": "right"
},
"options": [
{
"label": "A",
"value": "a"
},
{
"label": "B",
"value": "b"
},
{
"label": "C",
"value": "c"
}
]
},
{
"label": "300px 宽度中间对齐",
"type": "select",
"name": "select",
"menuTpl": "<div>${label} 值：${value}, 当前是否选中: ${checked}</div>",
"overlay": {
"width": 300,
"align": "center"
},
"options": [
{
"label": "A",
"value": "a"
},
{
"label": "B",
"value": "b"
},
{
"label": "C",
"value": "c"
}
]
}
]
}
}
使用相对数值，如：-20px 相当于 100% - 20px；+10vw 相当于 100% + 10vw。支持如上相同单位。
{
"type": "page",
"body": {
"type": "form",
"body": [
{
"label": "相对窄 100px 向左对齐",
"type": "select",
"name": "select",
"overlay": {
"width": "-100px",
"align": "left"
},
"popOverContainerSelector": "body",
"options": [
{
"label": "A",
"value": "a"
},
{
"label": "B",
"value": "b"
},
{
"label": "C",
"value": "c"
}
]
}
]
}
}
searchApi
发送
默认 GET，携带 term 变量，值为搜索框输入的文字，可从上下文中取数据设置进去。
响应
格式要求如下：
{
"status": 0,
"msg": "",
"data": {
"options": [
{
"label": "描述",
"value": "值" // ,
// "children": [] // 可以嵌套
},
{
"label": "描述2",
"value": "值2"
}
],
"value": "值" // 默认值，可以获取列表的同时设置默认值。
}
}
适用于需选择的数据/信息源较多时，用户可直观的知道自己所选择的数据/信息的场景，一般左侧框为数据/信息源，右侧为已选数据/信息，被选中信息同时存在于 2 个框内。
多选全选
开启全选后，默认开启"checkAllBySearch": true，检索状态下全选内容为当前过滤项。如果设置了"checkAllBySearch": false，则无论是否在检索状态下，全选都会选择全部数据源。
2.8.1 及以上版本
checkAllBySearch默认开启
{
"type": "form",
"body": [
{
"label": "多选",
"type": "select",
"name": "select2",
"searchable": true,
"checkAll": true,
"multiple": true,
"clearable": true,
"source": "/api/mock2/form/getOptions"
}
]
}
属性表
除了支持 普通表单项属性表 中的配置以外，还支持下面一些配置
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| options | Array<object>或Array<string> |
选项组 | |
| source | API 或 数据映射 | 动态选项组 | |
| autoComplete | API | 自动提示补全 | |
| delimiter | string |
false |
拼接符 |
| labelField | string |
"label" |
选项标签字段 |
| valueField | string |
"value" |
选项值字段 |
| joinValues | boolean |
true |
拼接值 |
| extractValue | boolean |
false |
提取值 |
| checkAll | boolean |
false |
是否支持全选 |
| checkAllLabel | string |
全选 |
全选的文字 |
| checkAllBySearch | boolean |
true |
有检索时只全选检索命中的项 |
| defaultCheckAll | boolean |
false |
默认是否全选 |
| creatable | boolean |
false |
新增选项 |
| multiple | boolean |
false |
多选 |
| searchable | boolean |
false |
检索 |
| filterOption | string |
(options: Option[], inputValue: string, option: {keys: string[]}) => Option[] |
|
| createBtnLabel | string |
"新增选项" |
新增选项 |
| addControls | Array<表单项> | 自定义新增表单项 | |
| addApi | API | 配置新增选项接口 | |
| editable | boolean |
false |
编辑选项 |
| editControls | Array<表单项> | 自定义编辑表单项 | |
| editApi | API | 配置编辑选项接口 | |
| removable | boolean |
false |
删除选项 |
| deleteApi | API | 配置删除选项接口 | |
| autoFill | object |
自动填充 | |
| menuTpl | string |
支持配置自定义菜单 | |
| clearable | boolean |
单选模式下是否支持清空 | |
| hideSelected | boolean |
false |
隐藏已选选项 |
| mobileClassName | string |
移动端浮层类名 | |
| selectMode | string |
`` | 可选：group、table、tree、chained、associated。分别为：列表形式、表格形式、树形选择形式、级联选择形式，关联选择形式（与级联选择的区别在于，级联是无限极，而关联只有一级，关联左边可以是个 tree）。 |
| searchResultMode | string |
如果不设置将采用 selectMode 的值，可以单独配置，参考 selectMode，决定搜索结果的展示形式。 |
|
| columns | Array<Object> |
当展示形式为 table 可以用来配置展示哪些列，跟 table 中的 columns 配置相似，只是只有展示功能。 |
|
| leftOptions | Array<Object> |
当展示形式为 associated 时用来配置左边的选项集。 |
|
| leftMode | string |
当展示形式为 associated 时用来配置左边的选择形式，支持 list 或者 tree。默认为 list。 |
|
| rightMode | string |
当展示形式为 associated 时用来配置右边的选择形式，可选：list、table、tree、chained。 |
|
| maxTagCount | number |
标签的最大展示数量，超出数量后以收纳浮层的方式展示，仅在多选模式开启后生效 | |
| overflowTagPopover | TooltipObject |
{"placement": "top", "trigger": "hover", "showArrow": false, "offset": [0, -10]} |
收纳浮层的配置属性，详细配置参考Tooltip |
| optionClassName | string |
选项 CSS 类名 | |
| popOverContainerSelector | string |
弹层挂载位置选择器，会通过querySelector获取 |
|
| clearable | boolean |
是否展示清空图标 | |
| overlay | { width: string | number, align: "left" | "center" | "right" } |
弹层宽度与对齐方式 2.8.0 以上版本 |
|
| showInvalidMatch | boolean |
false |
选项值与选项组不匹配时选项值是否飘红 |
事件表
当前组件会对外派发以下事件，可以通过onEvent来监听这些事件，并通过actions来配置执行的动作，在actions中可以通过${事件参数名}或${event.data.[事件参数名]}来获取事件产生的数据，详细请查看事件动作。
[name]表示当前组件绑定的名称，即name属性，如果没有配置name属性，则通过value取值。
| 事件名称 | 事件参数 | 说明 |
|---|---|---|
| change | [name]: string 组件的值selectedItems: Option | Option[] 选中的项items: Option[] 选项集合（< 2.3.2 及以下版本 为options） |
选中值变化时触发 |
| blur | [name]: string 组件的值items: Option[] 选项集合（< 2.3.2 及以下版本 为options） |
输入框失去焦点时触发 |
| focus | [name]: string 组件的值items: Option[] 选项集合（< 2.3.2 及以下版本 为options） |
输入框获取焦点时触发 |
| add | [name]: Option 新增的选项items: Option[] 选项集合（< 2.3.2 及以下版本 为options） |
新增选项提交时触发 |
| edit | [name]: Option 编辑的选项items: Option[] 选项集合（< 2.3.2 及以下版本 为options） |
编辑选项提交时触发 |
| delete | [name]: Option 删除的选项items: Option[] 选项集合（< 2.3.2 及以下版本 为options） |
删除选项提交时触发 |
动作表
当前组件对外暴露以下特性动作，其他组件可以通过指定actionType: 动作名称、componentId: 该组件id来触发这些动作，动作配置可以通过args: {动作配置项名称: xxx}来配置具体的参数，详细请查看事件动作。
| 动作名称 | 动作配置 | 说明 |
|---|---|---|
| clear | - | 清空 |
| reset | - | 将值重置为resetValue，若没有配置resetValue，则清空 |
| reload | - | 重新加载，调用 source，刷新数据域数据刷新（重新加载） |
| setValue | value: string | string[] 更新的值 |
更新数据，开启multiple支持设置多项，开启joinValues时，多值用,分隔，否则多值用数组 |