Select 选择器

概述

使用模拟的增强下拉选择器来代替浏览器原生的选择器。

选择器支持单选、多选、搜索,以及键盘快捷操作。

注意:非 template/render 模式下,需使用 i-selecti-option

代码示例

Select 选择器 - 图1

基础用法

基本用法。可以使用 v-model 双向绑定数据。

单选时,value 只接受字符串和数字类型,多选时,只接受数组类型,组件会自动根据Optionvalue来返回选中的数据。

可以给Select添加 style 样式,比如宽度。

在展开选择器后,可以使用键盘的updown快速上下选择,按下Enter选择,按下Esc收起选择器。

  1. <template>
  2. <Select v-model="model1" style="width:200px">
  3. <Option v-for="item in cityList" :value="item.value" :key="item.value">{{ item.label }}</Option>
  4. </Select>
  5. </template>
  6. <script>
  7. export default {
  8. data () {
  9. return {
  10. cityList: [
  11. {
  12. value: 'New York',
  13. label: 'New York'
  14. },
  15. {
  16. value: 'London',
  17. label: 'London'
  18. },
  19. {
  20. value: 'Sydney',
  21. label: 'Sydney'
  22. },
  23. {
  24. value: 'Ottawa',
  25. label: 'Ottawa'
  26. },
  27. {
  28. value: 'Paris',
  29. label: 'Paris'
  30. },
  31. {
  32. value: 'Canberra',
  33. label: 'Canberra'
  34. }
  35. ],
  36. model1: ''
  37. }
  38. }
  39. }
  40. </script>

Select 选择器 - 图2

尺寸

通过设置size属性为largesmall将输入框设置为大和小尺寸,不设置为默认(中)尺寸。

  1. <template>
  2. <Select v-model="model2" size="small" style="width:100px">
  3. <Option v-for="item in cityList" :value="item.value" :key="item.value">{{ item.label }}</Option>
  4. </Select>
  5. <Select v-model="model3" style="width:100px">
  6. <Option v-for="item in cityList" :value="item.value" :key="item.value">{{ item.label }}</Option>
  7. </Select>
  8. <Select v-model="model4" size="large" style="width:100px">
  9. <Option v-for="item in cityList" :value="item.value" :key="item.value">{{ item.label }}</Option>
  10. </Select>
  11. </template>
  12. <script>
  13. export default {
  14. data () {
  15. return {
  16. cityList: [
  17. {
  18. value: 'New York',
  19. label: 'New York'
  20. },
  21. {
  22. value: 'London',
  23. label: 'London'
  24. },
  25. {
  26. value: 'Sydney',
  27. label: 'Sydney'
  28. },
  29. {
  30. value: 'Ottawa',
  31. label: 'Ottawa'
  32. },
  33. {
  34. value: 'Paris',
  35. label: 'Paris'
  36. },
  37. {
  38. value: 'Canberra',
  39. label: 'Canberra'
  40. }
  41. ],
  42. model2: '',
  43. model3: '',
  44. model4: ''
  45. }
  46. }
  47. }
  48. </script>

Select 选择器 - 图3

禁用

通过给Select设置属性disabled禁用整个选择器。

通过给Option设置属性disabled可以禁用当前项。

  1. <template>
  2. <Select v-model="model5" disabled style="width:200px">
  3. <Option v-for="item in cityList" :value="item.value" :key="item.value">{{ item.label }}</Option>
  4. </Select>
  5. <Select v-model="model6" style="width:200px">
  6. <Option value="beijing">New York</Option>
  7. <Option value="shanghai" disabled>London</Option>
  8. <Option value="shenzhen">Sydney</Option>
  9. </Select>
  10. </template>
  11. <script>
  12. export default {
  13. data () {
  14. return {
  15. cityList: [
  16. {
  17. value: 'New York',
  18. label: 'New York'
  19. },
  20. {
  21. value: 'London',
  22. label: 'London'
  23. },
  24. {
  25. value: 'Sydney',
  26. label: 'Sydney'
  27. },
  28. {
  29. value: 'Ottawa',
  30. label: 'Ottawa'
  31. },
  32. {
  33. value: 'Paris',
  34. label: 'Paris'
  35. },
  36. {
  37. value: 'Canberra',
  38. label: 'Canberra'
  39. }
  40. ],
  41. model5: '',
  42. model6: ''
  43. }
  44. }
  45. }
  46. </script>

Select 选择器 - 图4

可清空

通过设置属性clearable可以清空已选项,仅适用于单选模式。

  1. <template>
  2. <Select v-model="model8" clearable style="width:200px">
  3. <Option v-for="item in cityList" :value="item.value" :key="item.value">{{ item.label }}</Option>
  4. </Select>
  5. </template>
  6. <script>
  7. export default {
  8. data () {
  9. return {
  10. cityList: [
  11. {
  12. value: 'New York',
  13. label: 'New York'
  14. },
  15. {
  16. value: 'London',
  17. label: 'London'
  18. },
  19. {
  20. value: 'Sydney',
  21. label: 'Sydney'
  22. },
  23. {
  24. value: 'Ottawa',
  25. label: 'Ottawa'
  26. },
  27. {
  28. value: 'Paris',
  29. label: 'Paris'
  30. },
  31. {
  32. value: 'Canberra',
  33. label: 'Canberra'
  34. }
  35. ],
  36. model8: ''
  37. }
  38. }
  39. }
  40. </script>

Select 选择器 - 图5

分组

使用OptionGroup可将选项进行分组。

  1. <template>
  2. <Select v-model="model7" style="width:200px">
  3. <OptionGroup label="Hot Cities">
  4. <Option v-for="item in cityList1" :value="item.value" :key="item.value">{{ item.label }}</Option>
  5. </OptionGroup>
  6. <OptionGroup label="Other Cities">
  7. <Option v-for="item in cityList2" :value="item.value" :key="item.value">{{ item.label }}</Option>
  8. </OptionGroup>
  9. </Select>
  10. </template>
  11. <script>
  12. export default {
  13. data () {
  14. return {
  15. cityList: [
  16. {
  17. value: 'New York',
  18. label: 'New York'
  19. },
  20. {
  21. value: 'London',
  22. label: 'London'
  23. },
  24. {
  25. value: 'Sydney',
  26. label: 'Sydney'
  27. },
  28. {
  29. value: 'Ottawa',
  30. label: 'Ottawa'
  31. },
  32. {
  33. value: 'Paris',
  34. label: 'Paris'
  35. },
  36. {
  37. value: 'Canberra',
  38. label: 'Canberra'
  39. }
  40. ],
  41. cityList1: [
  42. {
  43. value: 'New York',
  44. label: 'New York'
  45. },
  46. {
  47. value: 'London',
  48. label: 'London'
  49. },
  50. {
  51. value: 'Sydney',
  52. label: 'Sydney'
  53. }
  54. ],
  55. cityList2: [
  56. {
  57. value: 'Ottawa',
  58. label: 'Ottawa'
  59. },
  60. {
  61. value: 'Paris',
  62. label: 'Paris'
  63. },
  64. {
  65. value: 'Canberra',
  66. label: 'Canberra'
  67. }
  68. ],
  69. model7: ''
  70. }
  71. }
  72. }
  73. </script>

Select 选择器 - 图6

自定义模板

对选项内容可以进行自定义。注意在Option中使用label属性,可以让选择器优先读取该属性的值以显示,否则选中时显示的内容会和自定义的一样,这往往不是我们想要的。

对于选项显示内容的逻辑:优先显示 slot 内容,如果没有定义 slot,则显示label的值,如果没有设置 label,则显示value的值。

  1. <template>
  2. <Select v-model="model9" style="width:200px">
  3. <Option value="New York" label="New York">
  4. <span>New York</span>
  5. <span style="float:right;color:#ccc">America</span>
  6. </Option>
  7. <Option value="London" label="London">
  8. <span>London</span>
  9. <span style="float:right;color:#ccc">U.K.</span>
  10. </Option>
  11. <Option value="Sydney" label="Sydney">
  12. <span>Sydney</span>
  13. <span style="float:right;color:#ccc">Australian</span>
  14. </Option>
  15. </Select>
  16. </template>
  17. <script>
  18. export default {
  19. data () {
  20. return {
  21. model9: ''
  22. }
  23. }
  24. }
  25. </script>

Select 选择器 - 图7

多选

通过设置属性multiple可以开启多选模式。多选模式下,model 接受数组类型的数据,所返回的也是数组。

  1. <template>
  2. <Select v-model="model10" multiple style="width:260px">
  3. <Option v-for="item in cityList" :value="item.value" :key="item.value">{{ item.label }}</Option>
  4. </Select>
  5. </template>
  6. <script>
  7. export default {
  8. data () {
  9. return {
  10. cityList: [
  11. {
  12. value: 'New York',
  13. label: 'New York'
  14. },
  15. {
  16. value: 'London',
  17. label: 'London'
  18. },
  19. {
  20. value: 'Sydney',
  21. label: 'Sydney'
  22. },
  23. {
  24. value: 'Ottawa',
  25. label: 'Ottawa'
  26. },
  27. {
  28. value: 'Paris',
  29. label: 'Paris'
  30. },
  31. {
  32. value: 'Canberra',
  33. label: 'Canberra'
  34. }
  35. ],
  36. model10: []
  37. }
  38. }
  39. }
  40. </script>

Select 选择器 - 图8

前缀图标

设置 prefix 属性或 slot 可以在 Select 内显示前缀图标。

3.4.0 版本开始支持。
  1. <template>
  2. <Select v-model="model15" prefix="ios-home" style="width:200px">
  3. <Option v-for="item in cityList" :value="item.value" :key="item.value">{{ item.label }}</Option>
  4. </Select>
  5. <Select v-model="model15" style="width:200px">
  6. <Avatar src="https://dev-file.iviewui.com/userinfoPDvn9gKWYihR24SpgC319vXY8qniCqj4/avatar" slot="prefix" size="small" />
  7. <Option v-for="item in cityList" :value="item.value" :key="item.value">{{ item.label }}</Option>
  8. </Select>
  9. </template>
  10. <script>
  11. export default {
  12. data () {
  13. return {
  14. cityList: [
  15. {
  16. value: 'New York',
  17. label: 'New York'
  18. },
  19. {
  20. value: 'London',
  21. label: 'London'
  22. },
  23. {
  24. value: 'Sydney',
  25. label: 'Sydney'
  26. },
  27. {
  28. value: 'Ottawa',
  29. label: 'Ottawa'
  30. },
  31. {
  32. value: 'Paris',
  33. label: 'Paris'
  34. },
  35. {
  36. value: 'Canberra',
  37. label: 'Canberra'
  38. }
  39. ],
  40. model15: ''
  41. }
  42. }
  43. }
  44. </script>

Select 选择器 - 图9

标签集合

设置属性 max-tag-count 可指定最多显示的 tag 数量,超出后折叠。

设置属性 max-tag-placeholder 可以自定义 tag 超出后折叠的显示内容。

3.4.0 版本开始支持。
  1. <template>
  2. <Select v-model="model16" multiple :max-tag-count="2">
  3. <Option v-for="item in cityList" :value="item.value" :key="item.value">{{ item.label }}</Option>
  4. </Select>
  5. <Select v-model="model16" multiple :max-tag-count="2" :max-tag-placeholder="maxTagPlaceholder">
  6. <Option v-for="item in cityList" :value="item.value" :key="item.value">{{ item.label }}</Option>
  7. </Select>
  8. </template>
  9. <script>
  10. export default {
  11. data () {
  12. return {
  13. cityList: [
  14. {
  15. value: 'New York',
  16. label: 'New York'
  17. },
  18. {
  19. value: 'London',
  20. label: 'London'
  21. },
  22. {
  23. value: 'Sydney',
  24. label: 'Sydney'
  25. },
  26. {
  27. value: 'Ottawa',
  28. label: 'Ottawa'
  29. },
  30. {
  31. value: 'Paris',
  32. label: 'Paris'
  33. },
  34. {
  35. value: 'Canberra',
  36. label: 'Canberra'
  37. }
  38. ],
  39. model16: []
  40. }
  41. },
  42. methods: {
  43. maxTagPlaceholder (num) {
  44. return 'more '+ num;
  45. }
  46. }
  47. }
  48. </script>

Select 选择器 - 图10

可搜索

通过设置属性filterable可以开启搜索模式。单选和多选都支持搜索模式。多选搜索时,可以使用键盘Delete快捷删除最后一个已选项。

  1. <template>
  2. <Row>
  3. <Col span="12" style="padding-right:10px">
  4. <Select v-model="model11" filterable>
  5. <Option v-for="item in cityList" :value="item.value" :key="item.value">{{ item.label }}</Option>
  6. </Select>
  7. </Col>
  8. <Col span="12">
  9. <Select v-model="model12" filterable multiple>
  10. <Option v-for="item in cityList" :value="item.value" :key="item.value">{{ item.label }}</Option>
  11. </Select>
  12. </Col>
  13. </Row>
  14. </template>
  15. <script>
  16. export default {
  17. data () {
  18. return {
  19. cityList: [
  20. {
  21. value: 'New York',
  22. label: 'New York'
  23. },
  24. {
  25. value: 'London',
  26. label: 'London'
  27. },
  28. {
  29. value: 'Sydney',
  30. label: 'Sydney'
  31. },
  32. {
  33. value: 'Ottawa',
  34. label: 'Ottawa'
  35. },
  36. {
  37. value: 'Paris',
  38. label: 'Paris'
  39. },
  40. {
  41. value: 'Canberra',
  42. label: 'Canberra'
  43. }
  44. ],
  45. model11: '',
  46. model12: []
  47. }
  48. }
  49. }
  50. </script>

Select 选择器 - 图11

远程搜索

远程搜索需同时设置 filterableremoteremote-methodloading 四个 props,其中 loading 用于控制是否正在搜索中,remote-method 是远程搜索的方法。

注意:需要给 Option 设置 key。

设置初始显示值,需设置 label 属性。

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

  1. <template>
  2. <Row>
  3. <Col span="12" style="padding-right:10px">
  4. <Select
  5. v-model="model13"
  6. filterable
  7. remote
  8. :remote-method="remoteMethod1"
  9. :loading="loading1">
  10. <Option v-for="(option, index) in options1" :value="option.value" :key="index">{{option.label}}</Option>
  11. </Select>
  12. </Col>
  13. <Col span="12">
  14. <Select
  15. v-model="model14"
  16. multiple
  17. filterable
  18. remote
  19. :remote-method="remoteMethod2"
  20. :loading="loading2">
  21. <Option v-for="(option, index) in options2" :value="option.value" :key="index">{{option.label}}</Option>
  22. </Select>
  23. </Col>
  24. </Row>
  25. </template>
  26. <script>
  27. export default {
  28. data () {
  29. return {
  30. model13: '',
  31. loading1: false,
  32. options1: [],
  33. model14: [],
  34. loading2: false,
  35. options2: [],
  36. list: ['Alabama', 'Alaska', 'Arizona', 'Arkansas', 'California', 'Colorado', 'Connecticut', 'Delaware', 'Florida', 'Georgia', 'Hawaii', 'Idaho', 'Illinois', 'Indiana', 'Iowa', 'Kansas', 'Kentucky', 'Louisiana', 'Maine', 'Maryland', 'Massachusetts', 'Michigan', 'Minnesota', 'Mississippi', 'Missouri', 'Montana', 'Nebraska', 'Nevada', 'New hampshire', 'New jersey', 'New mexico', 'New york', 'North carolina', 'North dakota', 'Ohio', 'Oklahoma', 'Oregon', 'Pennsylvania', 'Rhode island', 'South carolina', 'South dakota', 'Tennessee', 'Texas', 'Utah', 'Vermont', 'Virginia', 'Washington', 'West virginia', 'Wisconsin', 'Wyoming']
  37. }
  38. },
  39. methods: {
  40. remoteMethod1 (query) {
  41. if (query !== '') {
  42. this.loading1 = true;
  43. setTimeout(() => {
  44. this.loading1 = false;
  45. const list = this.list.map(item => {
  46. return {
  47. value: item,
  48. label: item
  49. };
  50. });
  51. this.options1 = list.filter(item => item.label.toLowerCase().indexOf(query.toLowerCase()) > -1);
  52. }, 200);
  53. } else {
  54. this.options1 = [];
  55. }
  56. },
  57. remoteMethod2 (query) {
  58. if (query !== '') {
  59. this.loading2 = true;
  60. setTimeout(() => {
  61. this.loading2 = false;
  62. const list = this.list.map(item => {
  63. return {
  64. value: item,
  65. label: item
  66. };
  67. });
  68. this.options2 = list.filter(item => item.label.toLowerCase().indexOf(query.toLowerCase()) > -1);
  69. }, 200);
  70. } else {
  71. this.options2 = [];
  72. }
  73. }
  74. }
  75. }
  76. </script>

Select 选择器 - 图12

创建条目

4.0.0 在 filterable 模式下,开启属性 allow-create 可以通过在输入框中输入文字来创建新的条目。

输入新条目后,按下回车键即可新建条目。

需配合 @on-create 事件使用。

  1. <template>
  2. <Row>
  3. <Col span="12" style="padding-right:10px">
  4. <Select v-model="model17" filterable allow-create @on-create="handleCreate1">
  5. <Option v-for="item in cityList3" :value="item.value" :key="item.value">{{ item.label }}</Option>
  6. </Select>
  7. </Col>
  8. <Col span="12">
  9. <Select v-model="model18" filterable multiple allow-create @on-create="handleCreate2">
  10. <Option v-for="item in cityList4" :value="item.value" :key="item.value">{{ item.label }}</Option>
  11. </Select>
  12. </Col>
  13. </Row>
  14. </template>
  15. <script>
  16. export default {
  17. data () {
  18. return {
  19. cityList3: [
  20. {
  21. value: 'New York',
  22. label: 'New York'
  23. },
  24. {
  25. value: 'London',
  26. label: 'London'
  27. },
  28. {
  29. value: 'Sydney',
  30. label: 'Sydney'
  31. },
  32. {
  33. value: 'Ottawa',
  34. label: 'Ottawa'
  35. },
  36. {
  37. value: 'Paris',
  38. label: 'Paris'
  39. },
  40. {
  41. value: 'Canberra',
  42. label: 'Canberra'
  43. }
  44. ],
  45. cityList4: [
  46. {
  47. value: 'New York',
  48. label: 'New York'
  49. },
  50. {
  51. value: 'London',
  52. label: 'London'
  53. },
  54. {
  55. value: 'Sydney',
  56. label: 'Sydney'
  57. },
  58. {
  59. value: 'Ottawa',
  60. label: 'Ottawa'
  61. },
  62. {
  63. value: 'Paris',
  64. label: 'Paris'
  65. },
  66. {
  67. value: 'Canberra',
  68. label: 'Canberra'
  69. }
  70. ],
  71. model17: '',
  72. model18: []
  73. }
  74. },
  75. methods: {
  76. handleCreate1 (val) {
  77. this.cityList3.push({
  78. value: val,
  79. label: val
  80. });
  81. },
  82. handleCreate2 (val) {
  83. this.cityList4.push({
  84. value: val,
  85. label: val
  86. });
  87. }
  88. }
  89. }
  90. </script>

API

Select props

属性说明类型默认值
value指定选中项目的 value 值,可以使用 v-model 双向绑定数据。单选时只接受 String 或 Number,多选时只接受 ArrayString | Number | Array
multiple是否支持多选Booleanfalse
disabled是否禁用Booleanfalse
clearable是否可以清空选项,只在单选时有效Booleanfalse
filterable是否支持搜索Booleanfalse
remote是否使用远程搜索Booleanfalse
remote-method远程搜索的方法Function-
loading当前是否正在远程搜索Booleanfalse
loading-text远程搜索中的文字提示String加载中
label仅在 remote 模式下,初始化时使用。因为仅通过 value 无法得知选项的 label,需手动设置。String | Number | Array
size选择框大小,可选值为largesmalldefault或者不填String-
placeholder选择框默认文字String请选择
not-found-text当下拉列表为空时显示的内容String无匹配数据
label-in-value在返回选项时,是否将 label 和 value 一并返回,默认只返回 valueBooleanfalse
placement弹窗的展开方向,可选值为 topbottomtop-startbottom-starttop-endbottom-endStringbottom-start
transfer是否将弹层放置于 body 内,在 Tabs、带有 fixed 的 Table 列内使用时,建议添加此属性,它将不受父级样式影响,从而达到更好的效果Booleanfalse
element-id给表单元素设置 id,详见 Form 用法。String-
transfer-class-name 3.3.0开启 transfer 时,给浮层添加额外的 class 名称String-
prefix 3.4.0在 Select 内显示图标String-
max-tag-count 3.4.0多选时最多显示多少个 tagNumber-
max-tag-placeholder 3.4.0隐藏 tag 时显示的内容,参数是剩余项数量Function-
allow-create 4.0.0是否允许用户创建新条目,需开启 filterableBooleanfalse
capture 4.0.0是否开启 capture 模式,也可通过全局配置Booleantrue

Select events

事件名说明返回值
on-change选中的Option变化时触发,默认返回 value,如需返回 label,详见 label-in-value 属性当前选中项
on-query-change搜索词改变时触发query
on-clear点击清空按钮时触发
on-open-change下拉框展开或收起时触发true / false
on-create 4.0.0新建条目时触发query

Select methods

方法名说明参数
setQuery设置搜索词,为空时清空,仅在 filterable="true" 时有效query
clearSingleSelect清空单选项,仅在 clearable="true" 时有效

Select slot

名称说明
prefix 3.4.0自定义 Select 内头部图标

Option props

属性说明类型默认值
value选项值,默认根据此属性值进行筛选,必填String | Number
label选项显示的内容,默认会读取 slot,无 slot 时,优先读取该 label 值,无 label 时,读取 value。当选中时,选择器会显示 label 为已选文案。大部分情况不需要配置此项,直接写入 slot 即可,在自定义选项时,该属性非常有用。String-
disabled是否禁用当前项Booleanfalse
tag 4.0.0设置后,在多选时,标签内容会优先显示设置的值String | Number-

OptionGroup props

属性说明类型默认值
label分组的组名String