Cascader 级联选择

级联选择框。

何时使用

  • 需要从一组相关联的数据集合进行选择，例如省市区，公司层级，事物分类等。
  • 从一个较大的数据集合中进行选择时，用多级分类进行分隔，方便选择。

  • 比起 Select 组件，可以在同一个浮层中完成选择，有较好的体验。

    代码演示

Cascader级联选择 - 图1

基本

省市区级联。

  1. <template>
  2.   <a-cascader :options="options" placeholder="Please select" @change="onChange" />
  3. </template>
  4. <script>
  5. export default {
  6.   data() {
  7.     return {
  8.       options: [
  9.         {
  10.           value: 'zhejiang',
  11.           label: 'Zhejiang',
  12.           children: [
  13.             {
  14.               value: 'hangzhou',
  15.               label: 'Hangzhou',
  16.               children: [
  17.                 {
  18.                   value: 'xihu',
  19.                   label: 'West Lake',
  20.                 },
  21.               ],
  22.             },
  23.           ],
  24.         },
  25.         {
  26.           value: 'jiangsu',
  27.           label: 'Jiangsu',
  28.           children: [
  29.             {
  30.               value: 'nanjing',
  31.               label: 'Nanjing',
  32.               children: [
  33.                 {
  34.                   value: 'zhonghuamen',
  35.                   label: 'Zhong Hua Men',
  36.                 },
  37.               ],
  38.             },
  39.           ],
  40.         },
  41.       ],
  42.     };
  43.   },
  44.   methods: {
  45.     onChange(value) {
  46.       console.log(value);
  47.     },
  48.   },
  49. };
  50. </script>

Zhejiang / Hangzhou / West Lake (752100) Cascader级联选择 - 图2**Cascader级联选择 - 图3

自定义已选项

例如给最后一项加上邮编链接。

  1. <template>
  2.   <a-cascader
  3.     :options="options"
  4.     :default-value="['zhejiang', 'hangzhou', 'xihu']"
  5.     style="width: 100%"
  6.   >
  7.     <template slot="displayRender" slot-scope="{ labels, selectedOptions }">
  8.       <span v-for="(label, index) in labels" :key="selectedOptions[index].value">
  9.         <span v-if="index === labels.length - 1">
  10.           {{ label }} (<a @click="e => handleAreaClick(e, label, selectedOptions[index])">{{
  11.             selectedOptions[index].code
  12.           }}</a
  13.           >)
  14.         </span>
  15.         <span v-else @click="onChange"> {{ label }} / </span>
  16.       </span>
  17.     </template>
  18.   </a-cascader>
  19. </template>
  20. <script>
  21. export default {
  22.   data() {
  23.     return {
  24.       options: [
  25.         {
  26.           value: 'zhejiang',
  27.           label: 'Zhejiang',
  28.           children: [
  29.             {
  30.               value: 'hangzhou',
  31.               label: 'Hangzhou',
  32.               children: [
  33.                 {
  34.                   value: 'xihu',
  35.                   label: 'West Lake',
  36.                   code: 752100,
  37.                 },
  38.               ],
  39.             },
  40.           ],
  41.         },
  42.         {
  43.           value: 'jiangsu',
  44.           label: 'Jiangsu',
  45.           children: [
  46.             {
  47.               value: 'nanjing',
  48.               label: 'Nanjing',
  49.               children: [
  50.                 {
  51.                   value: 'zhonghuamen',
  52.                   label: 'Zhong Hua Men',
  53.                   code: 453400,
  54.                 },
  55.               ],
  56.             },
  57.           ],
  58.         },
  59.       ],
  60.     };
  61.   },
  62.   methods: {
  63.     onChange(value) {
  64.       console.log(value);
  65.     },
  66.     handleAreaClick(e, label, option) {
  67.       e.stopPropagation();
  68.       console.log('clicked', label, option);
  69.     },
  70.   },
  71. };
  72. </script>

Zhejiang / Hangzhou / West LakeCascader级联选择 - 图4**Cascader级联选择 - 图5

默认值

默认值通过数组的方式指定。

  1. <template>
  2.   <a-cascader
  3.     :options="options"
  4.     :default-value="['zhejiang', 'hangzhou', 'xihu']"
  5.     @change="onChange"
  6.   />
  7. </template>
  8. <script>
  9. export default {
  10.   data() {
  11.     return {
  12.       options: [
  13.         {
  14.           value: 'zhejiang',
  15.           label: 'Zhejiang',
  16.           children: [
  17.             {
  18.               value: 'hangzhou',
  19.               label: 'Hangzhou',
  20.               children: [
  21.                 {
  22.                   value: 'xihu',
  23.                   label: 'West Lake',
  24.                 },
  25.               ],
  26.             },
  27.           ],
  28.         },
  29.         {
  30.           value: 'jiangsu',
  31.           label: 'Jiangsu',
  32.           children: [
  33.             {
  34.               value: 'nanjing',
  35.               label: 'Nanjing',
  36.               children: [
  37.                 {
  38.                   value: 'zhonghuamen',
  39.                   label: 'Zhong Hua Men',
  40.                 },
  41.               ],
  42.             },
  43.           ],
  44.         },
  45.       ],
  46.     };
  47.   },
  48.   methods: {
  49.     onChange(value) {
  50.       console.log(value);
  51.     },
  52.   },
  53. };
  54. </script>

Cascader级联选择 - 图6

移入展开

通过移入展开下级菜单，点击完成选择。

  1. <template>
  2.   <a-cascader
  3.     :options="options"
  4.     :display-render="displayRender"
  5.     expand-trigger="hover"
  6.     placeholder="Please select"
  7.     @change="onChange"
  8.   />
  9. </template>
  10. <script>
  11. export default {
  12.   data() {
  13.     return {
  14.       options: [
  15.         {
  16.           value: 'zhejiang',
  17.           label: 'Zhejiang',
  18.           children: [
  19.             {
  20.               value: 'hangzhou',
  21.               label: 'Hangzhou',
  22.               children: [
  23.                 {
  24.                   value: 'xihu',
  25.                   label: 'West Lake',
  26.                 },
  27.               ],
  28.             },
  29.           ],
  30.         },
  31.         {
  32.           value: 'jiangsu',
  33.           label: 'Jiangsu',
  34.           children: [
  35.             {
  36.               value: 'nanjing',
  37.               label: 'Nanjing',
  38.               children: [
  39.                 {
  40.                   value: 'zhonghuamen',
  41.                   label: 'Zhong Hua Men',
  42.                 },
  43.               ],
  44.             },
  45.           ],
  46.         },
  47.       ],
  48.     };
  49.   },
  50.   methods: {
  51.     onChange(value) {
  52.       console.log(value);
  53.     },
  54.     displayRender({ labels }) {
  55.       return labels[labels.length - 1];
  56.     },
  57.   },
  58. };
  59. </script>

Cascader级联选择 - 图7

搜索

可以直接搜索选项并选择。

Cascader[showSearch] 暂不支持服务端搜索，更多信息见 #5547

  1. <template>
  2.   <a-cascader
  3.     :options="options"
  4.     :show-search="{ filter }"
  5.     placeholder="Please select"
  6.     @change="onChange"
  7.   />
  8. </template>
  9. <script>
  10. export default {
  11.   data() {
  12.     return {
  13.       options: [
  14.         {
  15.           value: 'zhejiang',
  16.           label: 'Zhejiang',
  17.           children: [
  18.             {
  19.               value: 'hangzhou',
  20.               label: 'Hangzhou',
  21.               children: [
  22.                 {
  23.                   value: 'xihu',
  24.                   label: 'West Lake',
  25.                 },
  26.                 {
  27.                   value: 'xiasha',
  28.                   label: 'Xia Sha',
  29.                   disabled: true,
  30.                 },
  31.               ],
  32.             },
  33.           ],
  34.         },
  35.         {
  36.           value: 'jiangsu',
  37.           label: 'Jiangsu',
  38.           children: [
  39.             {
  40.               value: 'nanjing',
  41.               label: 'Nanjing',
  42.               children: [
  43.                 {
  44.                   value: 'zhonghuamen',
  45.                   label: 'Zhong Hua men',
  46.                 },
  47.               ],
  48.             },
  49.           ],
  50.         },
  51.       ],
  52.     };
  53.   },
  54.   methods: {
  55.     onChange(value, selectedOptions) {
  56.       console.log(value, selectedOptions);
  57.     },
  58.     filter(inputValue, path) {
  59.       return path.some(option => option.label.toLowerCase().indexOf(inputValue.toLowerCase()) > -1);
  60.     },
  61.   },
  62. };
  63. </script>

Cascader级联选择 - 图8

自定义字段名

自定义字段名。

  1. <template>
  2.   <a-cascader
  3.     :field-names="{ label: 'name', value: 'code', children: 'items' }"
  4.     :options="options"
  5.     placeholder="Please select"
  6.     @change="onChange"
  7.   />
  8. </template>
  9. <script>
  10. const options = [
  11.   {
  12.     code: 'zhejiang',
  13.     name: 'Zhejiang',
  14.     items: [
  15.       {
  16.         code: 'hangzhou',
  17.         name: 'Hangzhou',
  18.         items: [
  19.           {
  20.             code: 'xihu',
  21.             name: 'West Lake',
  22.           },
  23.         ],
  24.       },
  25.     ],
  26.   },
  27.   {
  28.     code: 'jiangsu',
  29.     name: 'Jiangsu',
  30.     items: [
  31.       {
  32.         code: 'nanjing',
  33.         name: 'Nanjing',
  34.         items: [
  35.           {
  36.             code: 'zhonghuamen',
  37.             name: 'Zhong Hua Men',
  38.           },
  39.         ],
  40.       },
  41.     ],
  42.   },
  43. ];
  44. export default {
  45.   data() {
  46.     return {
  47.       options,
  48.     };
  49.   },
  50.   methods: {
  51.     onChange(value) {
  52.       console.log(value);
  53.     },
  54.   },
  55. };
  56. </script>

Cascader级联选择 - 图9

选择即改变

这种交互允许只选中父级选项。

  1. <template>
  2.   <a-cascader :options="options" change-on-select @change="onChange" />
  3. </template>
  4. <script>
  5. export default {
  6.   data() {
  7.     return {
  8.       options: [
  9.         {
  10.           value: 'zhejiang',
  11.           label: 'Zhejiang',
  12.           children: [
  13.             {
  14.               value: 'hangzhou',
  15.               label: 'Hangzhou',
  16.               children: [
  17.                 {
  18.                   value: 'xihu',
  19.                   label: 'West Lake',
  20.                 },
  21.               ],
  22.             },
  23.           ],
  24.         },
  25.         {
  26.           value: 'jiangsu',
  27.           label: 'Jiangsu',
  28.           children: [
  29.             {
  30.               value: 'nanjing',
  31.               label: 'Nanjing',
  32.               children: [
  33.                 {
  34.                   value: 'zhonghuamen',
  35.                   label: 'Zhong Hua Men',
  36.                 },
  37.               ],
  38.             },
  39.           ],
  40.         },
  41.       ],
  42.     };
  43.   },
  44.   methods: {
  45.     onChange(value) {
  46.       console.log(value);
  47.     },
  48.   },
  49. };
  50. </script>

Unselect Change city

可以自定义显示

切换按钮和结果分开。

  1. <template>
  2.   <span>
  3.     {{ text }} &nbsp;
  4.     <a-cascader :options="options" @change="onChange">
  5.       <a href="#">Change city</a>
  6.     </a-cascader>
  7.   </span>
  8. </template>
  9. <script>
  10. export default {
  11.   data() {
  12.     return {
  13.       text: 'Unselect',
  14.       options: [
  15.         {
  16.           value: 'zhejiang',
  17.           label: 'Zhejiang',
  18.           children: [
  19.             {
  20.               value: 'hangzhou',
  21.               label: 'Hangzhou',
  22.               children: [
  23.                 {
  24.                   value: 'xihu',
  25.                   label: 'West Lake',
  26.                 },
  27.               ],
  28.             },
  29.           ],
  30.         },
  31.         {
  32.           value: 'jiangsu',
  33.           label: 'Jiangsu',
  34.           children: [
  35.             {
  36.               value: 'nanjing',
  37.               label: 'Nanjing',
  38.               children: [
  39.                 {
  40.                   value: 'zhonghuamen',
  41.                   label: 'Zhong Hua Men',
  42.                 },
  43.               ],
  44.             },
  45.           ],
  46.         },
  47.       ],
  48.     };
  49.   },
  50.   methods: {
  51.     onChange(value, selectedOptions) {
  52.       this.text = selectedOptions.map(o => o.label).join(', ');
  53.     },
  54.   },
  55. };
  56. </script>

Cascader级联选择 - 图10

禁用选项

通过指定 options 里的 disabled 字段。

  1. <template>
  2.   <a-cascader :options="options" @change="onChange" />
  3. </template>
  4. <script>
  5. export default {
  6.   data() {
  7.     return {
  8.       options: [
  9.         {
  10.           value: 'zhejiang',
  11.           label: 'Zhejiang',
  12.           children: [
  13.             {
  14.               value: 'hangzhou',
  15.               label: 'Hangzhou',
  16.               children: [
  17.                 {
  18.                   value: 'xihu',
  19.                   label: 'West Lake',
  20.                 },
  21.               ],
  22.             },
  23.           ],
  24.         },
  25.         {
  26.           value: 'jiangsu',
  27.           label: 'Jiangsu',
  28.           disabled: true,
  29.           children: [
  30.             {
  31.               value: 'nanjing',
  32.               label: 'Nanjing',
  33.               children: [
  34.                 {
  35.                   value: 'zhonghuamen',
  36.                   label: 'Zhong Hua Men',
  37.                 },
  38.               ],
  39.             },
  40.           ],
  41.         },
  42.       ],
  43.     };
  44.   },
  45.   methods: {
  46.     onChange(value) {
  47.       console.log(value);
  48.     },
  49.   },
  50. };
  51. </script>

Cascader级联选择 - 图11

动态加载选项

使用 loadData 实现动态加载选项。

注意：loadData 与 showSearch 无法一起使用。

  1. <template>
  2.   <a-cascader
  3.     :options="options"
  4.     :load-data="loadData"
  5.     placeholder="Please select"
  6.     change-on-select
  7.     @change="onChange"
  8.   />
  9. </template>
  10. <script>
  11. export default {
  12.   data() {
  13.     return {
  14.       options: [
  15.         {
  16.           value: 'zhejiang',
  17.           label: 'Zhejiang',
  18.           isLeaf: false,
  19.         },
  20.         {
  21.           value: 'jiangsu',
  22.           label: 'Jiangsu',
  23.           isLeaf: false,
  24.         },
  25.       ],
  26.     };
  27.   },
  28.   methods: {
  29.     onChange(value) {
  30.       console.log(value);
  31.     },
  32.     loadData(selectedOptions) {
  33.       const targetOption = selectedOptions[selectedOptions.length - 1];
  34.       targetOption.loading = true;
  36.       // load options lazily
  37.       setTimeout(() => {
  38.         targetOption.loading = false;
  39.         targetOption.children = [
  40.           {
  41.             label: `${targetOption.label} Dynamic 1`,
  42.             value: 'dynamic1',
  43.           },
  44.           {
  45.             label: `${targetOption.label} Dynamic 2`,
  46.             value: 'dynamic2',
  47.           },
  48.         ];
  49.         this.options = [...this.options];
  50.       }, 1000);
  51.     },
  52.   },
  53. };
  54. </script>

Cascader级联选择 - 图12

大小

不同大小的级联选择器。

  1. <template>
  2.   <div>
  3.     <a-cascader size="large" :options="options" @change="onChange" /><br /><br />
  4.     <a-cascader :options="options" @change="onChange" /><br /><br />
  5.     <a-cascader size="small" :options="options" @change="onChange" /><br /><br />
  6.   </div>
  7. </template>
  8. <script>
  9. export default {
  10.   data() {
  11.     return {
  12.       options: [
  13.         {
  14.           value: 'zhejiang',
  15.           label: 'Zhejiang',
  16.           children: [
  17.             {
  18.               value: 'hangzhou',
  19.               label: 'Hangzhou',
  20.               children: [
  21.                 {
  22.                   value: 'xihu',
  23.                   label: 'West Lake',
  24.                 },
  25.               ],
  26.             },
  27.           ],
  28.         },
  29.         {
  30.           value: 'jiangsu',
  31.           label: 'Jiangsu',
  32.           children: [
  33.             {
  34.               value: 'nanjing',
  35.               label: 'Nanjing',
  36.               children: [
  37.                 {
  38.                   value: 'zhonghuamen',
  39.                   label: 'Zhong Hua Men',
  40.                 },
  41.               ],
  42.             },
  43.           ],
  44.         },
  45.       ],
  46.     };
  47.   },
  48.   methods: {
  49.     onChange(value) {
  50.       console.log(value);
  51.     },
  52.   },
  53. };
  54. </script>

Cascader级联选择 - 图13

后缀图标

省市区级联。

  1. <template>
  2.   <div>
  3.     <a-cascader
  4.       style="margin-top: 1rem"
  5.       :options="options"
  6.       placeholder="Please select"
  7.       @change="onChange"
  8.     >
  9.       <a-icon slot="suffixIcon" type="smile" class="test" />
  10.     </a-cascader>
  11.     <a-cascader
  12.       suffix-icon="ab"
  13.       style="margin-top: 1rem"
  14.       :options="options"
  15.       placeholder="Please select"
  16.       @change="onChange"
  17.     />
  18.   </div>
  19. </template>
  20. <script>
  21. export default {
  22.   data() {
  23.     return {
  24.       options: [
  25.         {
  26.           value: 'zhejiang',
  27.           label: 'Zhejiang',
  28.           children: [
  29.             {
  30.               value: 'hangzhou',
  31.               label: 'Hangzhou',
  32.               children: [
  33.                 {
  34.                   value: 'xihu',
  35.                   label: 'West Lake',
  36.                 },
  37.               ],
  38.             },
  39.           ],
  40.         },
  41.         {
  42.           value: 'jiangsu',
  43.           label: 'Jiangsu',
  44.           children: [
  45.             {
  46.               value: 'nanjing',
  47.               label: 'Nanjing',
  48.               children: [
  49.                 {
  50.                   value: 'zhonghuamen',
  51.                   label: 'Zhong Hua Men',
  52.                 },
  53.               ],
  54.             },
  55.           ],
  56.         },
  57.       ],
  58.     };
  59.   },
  60.   methods: {
  61.     onChange(value) {
  62.       console.log(value);
  63.     },
  64.   },
  65. };
  66. </script>

API

  1. <a-cascader :options="options" @change="onChange" />
参数说明类型默认值
allowClear是否支持清除booleantrue
autoFocus自动获取焦点booleanfalse
changeOnSelect当此项为 true 时，点选每级菜单选项值都会发生变化，具体见上面的演示booleanfalse
defaultValue默认的选中项string[] | number[][]
disabled禁用booleanfalse
displayRender选择后展示的渲染函数,可使用 slot=”displayRender” 和 slot-scope=”{labels, selectedOptions}”({labels, selectedOptions}) => vNodelabels => labels.join(‘ / ‘)
expandTrigger次级菜单的展开方式，可选 ‘click’ 和 ‘hover’string‘click’
fieldNames自定义 options 中 label name children 的字段object{ label: ‘label’, value: ‘value’, children: ‘children’ }
getPopupContainer菜单渲染父节点。默认渲染到 body 上，如果你遇到菜单滚动定位问题，试试修改为滚动的区域，并相对其定位。Function(triggerNode)() => document.body
loadData用于动态加载选项，无法与 showSearch 一起使用(selectedOptions) => void-
notFoundContent当下拉列表为空时显示的内容string‘Not Found’
options可选项数据源object-
placeholder输入框占位文本string‘请选择’
popupClassName自定义浮层类名string-
popupStyle自定义浮层样式object{}
popupPlacement浮层预设位置：bottomLeft bottomRight topLeft topRightEnumbottomLeft
popupVisible控制浮层显隐boolean-
showSearch在选择框中显示搜索框booleanfalse
size输入框大小，可选 large default smallstringdefault
suffixIcon自定义的选择框后缀图标string | VNode | slot-
value(v-model)指定选中项string[] | number[]-

showSearch 为对象时，其中的字段：

参数说明类型默认值
filter接收 inputValue path 两个参数，当 path 符合筛选条件时，应返回 true，反之则返回 false。function(inputValue, path): boolean
limit搜索结果展示数量number | false50
matchInputWidth搜索结果列表是否与输入框同宽boolean
render用于渲染 filter 后的选项,可使用 slot=”showSearchRender” 和 slot-scope=”{inputValue, path}”function({inputValue, path}): vNode
sort用于排序 filter 后的选项function(a, b, inputValue)

事件

事件名称说明回调参数版本
change选择完成后的回调(value, selectedOptions) => void-
popupVisibleChange显示/隐藏浮层的回调(value) => void-
search输入框变化时的回调(value) => void-

方法

名称描述
blur()移除焦点
focus()获取焦点

注意，如果需要获得中国省市区数据，可以参考 react 组件的实现 china-division。