amis2/docs/zh-CN/components/form/select.md

43 KiB
Executable File
Raw Blame History

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"
            }
          ]
        }
      ]
    }
  ]
}

延时加载

选型设置 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;支持单位: %pxrememvw

{
  "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 检索
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 `` 可选:grouptabletreechainedassociated。分别为:列表形式、表格形式、树形选择形式、级联选择形式,关联选择形式(与级联选择的区别在于,级联是无限极,而关联只有一级,关联左边可以是个 tree
searchResultMode string 如果不设置将采用 selectMode 的值,可以单独配置,参考 selectMode,决定搜索结果的展示形式。
columns Array<Object> 当展示形式为 table 可以用来配置展示哪些列,跟 table 中的 columns 配置相似,只是只有展示功能。
leftOptions Array<Object> 当展示形式为 associated 时用来配置左边的选项集。
leftMode string 当展示形式为 associated 时用来配置左边的选择形式,支持 list 或者 tree。默认为 list
rightMode string 当展示形式为 associated 时用来配置右边的选择形式,可选:listtabletreechained
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 以上版本

事件表

当前组件会对外派发以下事件,可以通过onEvent来监听这些事件,并通过actions来配置执行的动作,在actions中可以通过${事件参数名}来获取事件产生的数据(< 2.3.2 及以下版本 为 ${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时,多值用,分隔,否则多值用数组