# select (w-select)

- **Import**: `WSelect` from `win-design-next`
- **Tag**: `<w-select>`
- **说明**: Select 选择器
- **分类**: data-entry
- **Skill 版本**: V1.1.0
- **适配组件库**: win-design-next 1.2.2
- **API 来源**: `docs/zh-CN/component/select.md`、`docs/zh-CN/component/table-select.md`

## API

## Select API

### Attributes

| 参数                     | 说明                                                                                                               | 类型                                                                                                                                                                        | 默认值                                         | Version |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ------- |
| model-value / v-model    | 选中项绑定值                                                                                                       | ^[string] / ^[number] / ^[boolean] / ^[object] / ^[array]                                                                                                                   | —                                              |
| multiple                 | 是否多选                                                                                                           | ^[boolean]                                                                                                                                                                  | false                                          |
| disabled                 | 是否禁用                                                                                                           | ^[boolean]                                                                                                                                                                  | false                                          |
| value-key                | 作为 value 唯一标识的键名，绑定值为对象类型时必填                                                                  | ^[string]                                                                                                                                                                   | value                                          |
| size                     | 输入框尺寸                                                                                                         | ^[enum]`'' \| 'large' \| 'default' \| 'small'`                                                                                                                              | —                                              |
| clearable                | 是否可以清空选项                                                                                                   | ^[boolean]                                                                                                                                                                  | false                                          |
| collapse-tags            | 多选时是否将选中值按文字的形式展示                                                                                 | ^[boolean]                                                                                                                                                                  | false                                          |
| collapse-tags-tooltip    | 当鼠标悬停于折叠标签的文本时，是否显示所有选中的标签。 要使用此属性，`collapse-tags`属性必须设定为 true            | ^[boolean]                                                                                                                                                                  | true                                           |
| multiple-limit           | `multiple` 属性设置为 `true` 时，代表多选场景下用户最多可以选择的项目数， 为 0 则不限制                            | ^[number]                                                                                                                                                                   | 0                                              |
| name                     | Select 输入框的原生 name 属性                                                                                      | ^[string]                                                                                                                                                                   | —                                              |
| effect                   | tooltip 主题，内置了 `dark` / `light` 两种                                                                         | ^[enum]`'dark' \| 'light'` / ^[string]                                                                                                                                      | lighter                                        |
| autocomplete             | Select 输入框的原生 autocomplete 属性                                                                              | ^[string]                                                                                                                                                                   | off                                            |
| placeholder              | 占位符，默认为“Select”                                                                                             | ^[string]                                                                                                                                                                   | —                                              |
| filterable               | Select 组件是否可筛选                                                                                              | ^[boolean]                                                                                                                                                                  | false                                          |
| allow-create             | 是否允许用户创建新条目， 只有当 `filterable` 设置为 true 时才会生效。                                              | ^[boolean]                                                                                                                                                                  | false                                          |
| filter-method            | 自定义筛选方法                                                                                                     | ^[Function]`() => void`                                                                                                                                                     | —                                              |
| remote                   | 其中的选项是否从服务器远程加载                                                                                     | ^[boolean]                                                                                                                                                                  | false                                          |
| remote-method            | 自定义远程搜索方法                                                                                                 | ^[Function]`() => void`                                                                                                                                                     | —                                              |
| loading                  | 是否正在从远程获取数据                                                                                             | ^[boolean]                                                                                                                                                                  | false                                          |
| loading-text             | 从服务器加载数据时显示的文本，默认为“Loading”                                                                      | ^[string]                                                                                                                                                                   | —                                              |
| no-match-text            | 搜索条件无匹配时显示的文字，也可以使用 `empty` 插槽设置，默认是 “No matching data'”                                | ^[string]                                                                                                                                                                   | —                                              |
| no-data-text             | 无选项时显示的文字，也可以使用 `empty` 插槽设置自定义内容，默认是 “暂无数据”                                       | ^[string]                                                                                                                                                                   | —                                              |
| popper-class             | 选择器下拉菜单的自定义类名                                                                                         | ^[string]                                                                                                                                                                   | ''                                             |
| popper-style ^(1.1.1)    | 为 Select 下拉菜单和标签提示设置自定义样式                                                                         | ^[string] / ^[object]                                                                                                                                                       | —                                              |
| reserve-keyword          | 当 `multiple` 和 `filterable`被设置为 true 时，是否在选中一个选项后保留当前的搜索关键词                            | ^[boolean]                                                                                                                                                                  | true                                           |
| default-first-option     | 是否在输入框按下回车时，选择第一个匹配项。 需配合 `filterable` 或 `remote` 使用                                    | ^[boolean]                                                                                                                                                                  | false                                          |
| teleported               | 是否使用 teleport。设置成 `true`则会被追加到 `append-to` 的位置                                                    | ^[boolean]                                                                                                                                                                  | true                                           |
| append-to                | 下拉框挂载到哪个 DOM 元素                                                                                          | ^[string]                                                                                                                                                                   | —                                              |
| persistent               | 当下拉选择器未被激活并且`persistent`设置为`false`，选择器会被删除。                                                | ^[boolean]                                                                                                                                                                  | true                                           |
| automatic-dropdown       | 对于不可搜索的 Select，是否在输入框获得焦点后自动弹出选项菜单                                                      | ^[boolean]                                                                                                                                                                  | false                                          |
| clear-icon               | 自定义清除图标                                                                                                     | ^[string] / ^[object]`Component`                                                                                                                                            | CircleCloseFilled                              |
| fit-input-width          | 下拉框的宽度是否与输入框相同                                                                                       | ^[boolean]                                                                                                                                                                  | false                                          |
| suffix-icon              | 自定义后缀图标组件                                                                                                 | ^[string] / ^[object]`Component`                                                                                                                                            |                                                |
| suffix-icon-rotate       | 自定义后缀图标组件是否旋转                                                                                         | ^[boolean]                                                                                                                                                                  | true                                           |
| tag-type                 | 标签类型                                                                                                           | ^[enum]`'' \| 'success' \| 'info' \| 'warning' \| 'error' \| 'danger'`                                                                                                      | info                                           |
| tag-effect               | 标签效果                                                                                                           | ^[enum]`'' \| 'light' \| 'dark' \| 'plain'`                                                                                                                                 | light                                          |
| validate-event           | 是否触发表单验证                                                                                                   | ^[boolean]                                                                                                                                                                  | true                                           |
| offset                   | 下拉面板偏移量                                                                                                     | ^[number]                                                                                                                                                                   | 12                                             |
| show-arrow               | 下拉菜单的内容是否有箭头                                                                                           | ^[boolean]                                                                                                                                                                  | false                                          |
| placement                | 下拉框出现的位置                                                                                                   | ^[enum]`'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | bottom-start                                   |
| fallback-placements      | dropdown 可用的 positions 请查看[popper.js 文档](https://popper.js.org/docs/v2/modifiers/flip/#fallbackplacements) | ^[array]`Placement[]`                                                                                                                                                       | ['bottom-start', 'top-start', 'right', 'left'] |
| max-collapse-tags        | 需要显示的 Tag 的最大数量 只有当 `collapse-tags` 设置为 true 时才会生效。                                          | ^[number]                                                                                                                                                                   | 1                                              |
| popper-options           | [popper.js](https://popper.js.org/docs/v2/) 参数                                                                   | ^[object]refer to [popper.js](https://popper.js.org/docs/v2/) doc                                                                                                           | {}                                             |
| aria-label ^(a11y)       | 等价于原生 input `aria-label` 属性                                                                                 | ^[string]                                                                                                                                                                   | —                                              |
| empty-values             | 组件的空值配置 [参考 config-provider](/zh-CN/component/config-provider#empty-values-configurations)                | ^[array]                                                                                                                                                                    | —                                              |
| value-on-clear           | 清空选项的值 [参考 config-provider](/zh-CN/component/config-provider#empty-values-configurations)                  | ^[string] / ^[number] / ^[boolean] / ^[Function]                                                                                                                            | —                                              |
| tabindex                 | input 的 tabindex                                                                                                  | ^[string] / ^[number]                                                                                                                                                       | —                                              |
| plain                    | 朴素的 Select                                                                                                      | ^[boolean]                                                                                                                                                                  | false                                          | V0.0.8  |
| options ^(1.1.1)         | 选项的数据源 `value` and `label` and `disabled` 可以通过 `props`自定义                                             | ^[array]`Array`                                                                                                                                                             | —                                              |
| [props](#props) ^(1.1.1) | 配置 options                                                                                                       | ^[object]                                                                                                                                                                   | —                                              |
| debounce ^(1.1.1)        | 远程搜索时的防抖延迟（以毫秒为单位）                                                                               | ^[number]                                                                                                                                                                   | 300                                            |

### props

| Attribute | Description                            | Type      | Default  |
| --------- | -------------------------------------- | --------- | -------- |
| value     | 指定选项的值为选项对象的某个属性值     | ^[string] | value    |
| label     | 指定节点标签为节点对象的某个属性值     | ^[string] | label    |
| options   | 指定选项的子选项为选项对象的某个属性值 | ^[string] | options  |
| disabled  | 指定选项的禁用为选项对象的某个属性值   | ^[string] | disabled |

### Events

| 事件名         | 说明                                     | Type                                                                |
| -------------- | ---------------------------------------- | ------------------------------------------------------------------- |
| change         | 选中值发生变化时触发                     | ^[Function]`(value: any) => void`                                   |
| visible-change | 下拉框出现/隐藏时触发                    | ^[Function]`(visible: boolean) => void`                             |
| remove-tag     | 多选模式下移除 tag 时触发                | ^[Function]`(tagValue: any) => void`                                |
| clear          | 可清空的单选模式下用户点击清空按钮时触发 | ^[Function]`() => void`                                             |
| blur           | 当 input 失去焦点时触发                  | ^[Function]`(event: FocusEvent) => void`                            |
| focus          | 当 input 获得焦点时触发                  | ^[Function]`(event: FocusEvent) => void`                            |
| popup-scroll   | 下拉滚动时触发                           | ^[Function]`(data:{scrollTop: number, scrollLeft: number}) => void` |

### Slots

| 插槽名  | 说明                           | 子标签                |
| ------- | ------------------------------ | --------------------- |
| default | option 组件列表                | Option Group / Option |
| header  | 下拉列表顶部的内容             | —                     |
| footer  | 下拉列表底部的内容             | —                     |
| prefix  | Select 组件头部内容            | —                     |
| empty   | 无选项时的列表                 | —                     |
| tag     | select 组件自定义标签内容      | —                     |
| loading | select 组件自定义 loading 内容 | —                     |
| label   | select 组件自定义标签内容      | —                     |

### Exposes

| 插槽名        | 说明                                   | 类型                    |
| ------------- | -------------------------------------- | ----------------------- |
| focus         | 使选择器的输入框获取焦点               | ^[Function]`() => void` |
| blur          | 使选择器的输入框失去焦点，并隐藏下拉框 | ^[Function]`() => void` |
| selectedLabel | 获取当前选中的标签                     | ^[object]`ComputedRef`  |

## Select API

### Attributes

| 参数                  | 说明                                                                                                               | 类型                                                                                                                                                                        | 默认值                                         | Version  |
| --------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | -------- |
| options               | 选项的数据源 `value` and `label` and `disabled` 可以通过 `props`自定义                                             | ^[array]`Array`                                                                                                                                                             | —                                              |
| columns               | 列配置项                                                                                                           | Array                                                                                                                                                                       | —                                              |
| table-size            | Table 的尺寸                                                                                                       | ^[enum]`'extra-large' \| 'large' \| 'default' \| 'small' \| 'mini'`                                                                                                         | default                                        |
| table-width           | table 宽度                                                                                                         | Number/String                                                                                                                                                               | 500                                            |
| table-max-height      | table 高度                                                                                                         | Number/String                                                                                                                                                               | 300                                            |
| model-value / v-model | 选中项绑定值                                                                                                       | ^[string] / ^[number] / ^[boolean] / ^[object] / ^[array]                                                                                                                   | —                                              |
| multiple              | 是否多选                                                                                                           | ^[boolean]                                                                                                                                                                  | false                                          |
| disabled              | 是否禁用                                                                                                           | ^[boolean]                                                                                                                                                                  | false                                          |
| size                  | 输入框尺寸                                                                                                         | ^[enum]`'' \| 'large' \| 'default' \| 'small'`                                                                                                                              | —                                              |
| clearable             | 是否可以清空选项                                                                                                   | ^[boolean]                                                                                                                                                                  | false                                          |
| collapse-tags         | 多选时是否将选中值按文字的形式展示                                                                                 | ^[boolean]                                                                                                                                                                  | false                                          |
| collapse-tags-tooltip | 当鼠标悬停于折叠标签的文本时，是否显示所有选中的标签。 要使用此属性，`collapse-tags`属性必须设定为 true            | ^[boolean]                                                                                                                                                                  | true                                           |
| multiple-limit        | `multiple` 属性设置为 `true` 时，代表多选场景下用户最多可以选择的项目数， 为 0 则不限制                            | ^[number]                                                                                                                                                                   | 0                                              |
| name                  | Select 输入框的原生 name 属性                                                                                      | ^[string]                                                                                                                                                                   | —                                              |
| effect                | tooltip 主题，内置了 `dark` / `light` 两种                                                                         | ^[enum]`'dark' \| 'light'` / ^[string]                                                                                                                                      | lighter                                        |
| autocomplete          | Select 输入框的原生 autocomplete 属性                                                                              | ^[string]                                                                                                                                                                   | off                                            |
| placeholder           | 占位符，默认为“Select”                                                                                             | ^[string]                                                                                                                                                                   | —                                              |
| filterable            | Select 组件是否可筛选                                                                                              | ^[boolean]                                                                                                                                                                  | false                                          |
| filter-method         | 自定义筛选方法                                                                                                     | ^[Function]`() => void`                                                                                                                                                     | —                                              |
| remote                | 其中的选项是否从服务器远程加载                                                                                     | ^[boolean]                                                                                                                                                                  | false                                          |
| remote-open-on-search | 远程搜索聚焦输入框时是否自动打开下拉弹窗                                                                           | ^[boolean]                                                                                                                                                                  | false                                          | ^(1.2.2) |
| remote-method         | 自定义远程搜索方法                                                                                                 | ^[Function]`() => void`                                                                                                                                                     | —                                              |
| loading               | 是否正在从远程获取数据                                                                                             | ^[boolean]                                                                                                                                                                  | false                                          |
| loading-text          | 从服务器加载数据时显示的文本，默认为“Loading”                                                                      | ^[string]                                                                                                                                                                   | —                                              |
| no-match-text         | 搜索条件无匹配时显示的文字，也可以使用 `empty` 插槽设置，默认是 “No matching data'”                                | ^[string]                                                                                                                                                                   | —                                              |
| no-data-text          | 无选项时显示的文字，也可以使用 `empty` 插槽设置自定义内容，默认是 “暂无数据”                                       | ^[string]                                                                                                                                                                   | —                                              |
| popper-class          | 选择器下拉菜单的自定义类名                                                                                         | ^[string]                                                                                                                                                                   | ''                                             |
| popper-style          | 为 Select 下拉菜单和标签提示设置自定义样式                                                                         | ^[string] / ^[object]                                                                                                                                                       | —                                              |
| reserve-keyword       | 当 `multiple` 和 `filterable`被设置为 true 时，是否在选中一个选项后保留当前的搜索关键词                            | ^[boolean]                                                                                                                                                                  | true                                           |
| default-first-option  | 是否在输入框按下回车时，选择第一个匹配项。 需配合 `filterable` 或 `remote` 使用                                    | ^[boolean]                                                                                                                                                                  | false                                          |
| teleported            | 是否使用 teleport。设置成 `true`则会被追加到 `append-to` 的位置                                                    | ^[boolean]                                                                                                                                                                  | true                                           |
| append-to             | 下拉框挂载到哪个 DOM 元素                                                                                          | ^[string]                                                                                                                                                                   | —                                              |
| persistent            | 当下拉选择器未被激活并且`persistent`设置为`false`，选择器会被删除。                                                | ^[boolean]                                                                                                                                                                  | true                                           |
| automatic-dropdown    | 对于不可搜索的 Select，是否在输入框获得焦点后自动弹出选项菜单                                                      | ^[boolean]                                                                                                                                                                  | false                                          |
| clear-icon            | 自定义清除图标                                                                                                     | ^[string] / ^[object]`Component`                                                                                                                                            | CircleCloseFilled                              |
| fit-input-width       | 下拉框的宽度是否与输入框相同                                                                                       | ^[boolean]                                                                                                                                                                  | false                                          |
| suffix-icon           | 自定义后缀图标组件                                                                                                 | ^[string] / ^[object]`Component`                                                                                                                                            |                                                |
| suffix-icon-rotate    | 自定义后缀图标组件是否旋转                                                                                         | ^[boolean]                                                                                                                                                                  | true                                           |
| tag-type              | 标签类型                                                                                                           | ^[enum]`'' \| 'success' \| 'info' \| 'warning' \| 'error' \| 'danger'`                                                                                                      | info                                           |
| tag-effect            | 标签效果                                                                                                           | ^[enum]`'' \| 'light' \| 'dark' \| 'plain'`                                                                                                                                 | light                                          |
| validate-event        | 是否触发表单验证                                                                                                   | ^[boolean]                                                                                                                                                                  | true                                           |
| offset                | 下拉面板偏移量                                                                                                     | ^[number]                                                                                                                                                                   | 12                                             |
| show-arrow            | 下拉菜单的内容是否有箭头                                                                                           | ^[boolean]                                                                                                                                                                  | false                                          |
| placement             | 下拉框出现的位置                                                                                                   | ^[enum]`'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | bottom-start                                   |
| fallback-placements   | dropdown 可用的 positions 请查看[popper.js 文档](https://popper.js.org/docs/v2/modifiers/flip/#fallbackplacements) | ^[array]`Placement[]`                                                                                                                                                       | ['bottom-start', 'top-start', 'right', 'left'] |
| max-collapse-tags     | 需要显示的 Tag 的最大数量 只有当 `collapse-tags` 设置为 true 时才会生效。                                          | ^[number]                                                                                                                                                                   | 1                                              |
| aria-label ^(a11y)    | 等价于原生 input `aria-label` 属性                                                                                 | ^[string]                                                                                                                                                                   | —                                              |
| empty-values          | 组件的空值配置 [参考 config-provider](/zh-CN/component/config-provider#empty-values-configurations)                | ^[array]                                                                                                                                                                    | —                                              |
| value-on-clear        | 清空选项的值 [参考 config-provider](/zh-CN/component/config-provider#empty-values-configurations)                  | ^[string] / ^[number] / ^[boolean] / ^[Function]                                                                                                                            | —                                              |
| tabindex              | input 的 tabindex                                                                                                  | ^[string] / ^[number]                                                                                                                                                       | —                                              |
| plain                 | 朴素的 Select                                                                                                      | ^[boolean]                                                                                                                                                                  | false                                          | V0.0.8   |
| [props](#props)       | 配置 options                                                                                                       | ^[object]                                                                                                                                                                   | —                                              |
| debounce              | 远程搜索时的防抖延迟（以毫秒为单位）                                                                               | ^[number]                                                                                                                                                                   | 300                                            |

### props

| Attribute | Description                          | Type      | Default  |
| --------- | ------------------------------------ | --------- | -------- |
| value     | 指定选项的值为选项对象的某个属性值   | ^[string] | value    |
| label     | 指定节点标签为节点对象的某个属性值   | ^[string] | label    |
| disabled  | 指定选项的禁用为选项对象的某个属性值 | ^[string] | disabled |

### Events

| 事件名                   | 说明                                       | Type                                                                                      |
| ------------------------ | ------------------------------------------ | ----------------------------------------------------------------------------------------- |
| change                   | 选中值发生变化时触发                       | ^[Function]`(value: any, selectedOptions: any[]) => void`                                 |
| visible-change           | 下拉框出现/隐藏时触发                      | ^[Function]`(visible: boolean) => void`                                                   |
| remove-tag               | 多选模式下移除 tag 时触发                  | ^[Function]`(tagValue: any) => void`                                                      |
| clear                    | 可清空的单选模式下用户点击清空按钮时触发   | ^[Function]`() => void`                                                                   |
| blur                     | 当 input 失去焦点时触发                    | ^[Function]`(event: FocusEvent) => void`                                                  |
| focus                    | 当 input 获得焦点时触发                    | ^[Function]`(event: FocusEvent) => void`                                                  |
| header-dragend ^(1.1.15) | 当拖动表头改变了列的宽度的时候会触发该事件 | ^[Function]`(newWidth: number, oldWidth: number, column: any, event: MouseEvent) => void` |

### Slots

| 插槽名  | 说明                           | 子标签 |
| ------- | ------------------------------ | ------ |
| header  | 下拉列表顶部的内容             | —      |
| footer  | 下拉列表底部的内容             | —      |
| prefix  | Select 组件头部内容            | —      |
| empty   | 无选项时的列表                 | —      |
| tag     | select 组件自定义标签内容      | —      |
| loading | select 组件自定义 loading 内容 | —      |
| label   | select 组件自定义标签内容      | —      |

### Exposes

| 插槽名        | 说明                                   | 类型                    |
| ------------- | -------------------------------------- | ----------------------- |
| focus         | 使选择器的输入框获取焦点               | ^[Function]`() => void` |
| blur          | 使选择器的输入框失去焦点，并隐藏下拉框 | ^[Function]`() => void` |
| selectedLabel | 获取当前选中的标签                     | ^[object]`ComputedRef`  |
