# MultiSelect 多项选择器

# MultiSelect 概述

资管版本特殊多项选择器 使用模拟的下拉选择器来代替浏览器原生的选择器，选择器支持多选、搜索，以及键盘快捷操作（交互形式趋近于桌面端）。

TIP

注意：该组件是高定制化组件，本组件仅支持基本场景的功能（详见官网文档），复杂业务场景及影响性能的场景不支持。使用前请做好充足的调研。

# MultiSelect 代码演示

# 基础用法与场景描述

可以使用 v-model 双向绑定数据。
选中多个选项后，选项值为用 , 逗号分割的字符串，允许复制粘贴选项(注意组件根据label进行匹配)。
点击控件主体会展开下拉面板，若有已选项会对选项高亮，输入框中的已选项文本会被全选中，在展开选择器后，可以使用键盘的 up 和 down 快速上下选择，按下 space 选中/取消选项，按下 Esc 收起下拉面板。选中选项后，焦点仍在输入框不丢失，且文本全选状态，方便操作立即删除已选项。
用键盘tab、up或down键快速切入焦点，控件不展开下拉面板，若有已选项输入框中的已选文本会被全选中,输入框键入可立即唤起下拉面板。
开启展示多列 showCol 下拉面板中显示多列，colWidth 配置多列文本的宽度.

# 禁用

通过设置属性 disabled 禁用整个选择器，设置属性 readonly 将选择器只读状态。

# 远程搜索

远程搜索需同时设置 remote 、 remote-method 两个 props，其中 loading 用于控制是否正在搜索中，remote-method 是远程搜索的方法。loading-text 为远程搜索中的文字提示 ,默认显示加载中。

本例为美国州名，尝试输入一些字母。

# 选择框默认文字

通过 placeholder 属性设置选择框默认文字，不设置默认为请选择。

# 弹窗的展开方向

通过 placement 弹窗的展开方向，可选值为 bottom 和 top。默认值为 bottom。

# 选项互斥

开启了 specialIndex 属性，默认 value 为 -99999 的选项将与其他选项互斥
也可通过设置 specialVal 传入一个指定的特殊值。

# 下拉框宽度设置

dropWidth 设置下拉框宽度，不设置时等于输入框宽度。
maxDropWidth 下拉框的自适应时设置的最大宽度，实际值会取输入框宽度与 maxDropWidth 的最大值。

# MultiSelect API

# MultiSelect props

属性	说明	类型	默认值
value	指定选中项目的 value 值，可以使用 v-model 双向绑定数据。单选时只接受 String 或 Number	String \| Number	空
animated	是否开启下拉框动画效果	Boolean	true
width	组件输入框的宽度	Number	空
disabled	是否禁用	Boolean	false
readonly	是否只读	Boolean	false
label-in-value	在 on-change 返回选项时，是否将 label 和 value 一并返回，默认只返回 value	Boolean	false
specialIndex	是否开启特殊项目，选择特殊项与其他项互斥	Boolean	false
specialVal	特殊项关键值	String	"-99999"
remote	是否使用远程搜索	Boolean	false
remote-method	远程搜索的方法	Function	-
loading	当前是否正在远程搜索	Boolean	false
loading-text	远程搜索中的文字提示	String	加载中
placeholder	选择框默认文字	String	请选择
tooltip	鼠标在输入框悬浮时显示额外的提示信息	Boolean	true
placement	弹窗的展开方向，可选值为 `bottom` 、 `top`	String	bottom
autoPlacement	日期面板方向自适应，其相对于外部第一个非静态定位父元素开始定位	Boolean	false
transfer	是否将弹层放置于 body 内，它将不受父级样式影响，从而达到更好的效果	Boolean	false
widthAdaption	下拉框的宽度是否随着内容自适应，以width设置的宽度为最小宽度，最大宽度取输入框宽度与 maxDropWidth 的最大值	500
dropWidth	设置下拉框的宽度,不设置时下拉框的宽度等于输入框宽度	String/Number	-
maxDropWidth	下拉框的自适应时设置的最大宽度，实际值会取输入框宽度与 maxDropWidth 的最大值	String / Number	500
tabindex	设置输入框 tabindex	String \| Number	-1
limitLength	限制value值长度	String \| Number	-
canDragValue	控制是否可通过鼠标拖拽的形式将文本内容拖入、拖出输入框	Boolean	false

# MultiSelect events

事件名	说明	返回值
on-change	选中的 `Option` 变化时触发，默认返回 `value`，如需返回 `label`，详见 `label-in-value` 属性	当前选中项
on-query-change	搜索词改变时触发	搜索值
on-blur	失去焦点时触发	无
on-focus	获取焦点时触发	无
on-drop-change	弹框关闭/展开时触发	弹窗状态
on-keydown	键盘按键按下触发	参数一：当前输入框的搜索值 `query` 参数二：原生事件对象 `event`
on-keyup	键盘按键弹起触发	参数一：当前输入框的搜索值 `query` 参数二：原生事件对象 `event`
on-paste	输入框粘贴时触发	obj对象包括 oldVal 和 newVal

# MultiSelect methods

方法名	说明	参数
toggleSelect	全选/全不选 `this.$refs.xxx.toggleSelect(status)`	status:true/false
fold	调用收起下拉面板 `this.$refs.xxx.fold()`	无
focus	手动聚焦输入框 `this.$refs.xxx.focus()`	无
blur	手动取消输入框焦点 `this.$refs.xxx.blur()` 失焦同时会选中当前关键字匹配项，或选中第一项	无

# Block props

属性	说明	类型
data	选项集，必填	Array
showCol	多列显示配置	Array
colHeight	多列文本高度配置	String

# Block events

事件名	说明	返回值
on-scroll	下拉框滚动时触发	第一个参数为滚动条距离底部的高度；第二个参数是列表的scrollTop；第三个参数为滚动方向（"x"代表水平滚动，"y"代表垂直滚动）