Cascader 级联选择

级联选择框。

何时使用

  • 需要从一组相关联的数据集合进行选择，例如省市区，公司层级，事物分类等。
  • 从一个较大的数据集合中进行选择时，用多级分类进行分隔，方便选择。
  • 比起 Select 组件，可以在同一个浮层中完成选择，有较好的体验。

代码演示

基本用法

省市区级联。

<template>
  <a-cascader v-model:value="value" :options="options" placeholder="Please select" />
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
interface Option {
  value: string;
  label: string;
  children?: Option[];
}
const options: Option[] = [
  {
    value: 'zhejiang',
    label: 'Zhejiang',
    children: [
      {
        value: 'hangzhou',
        label: 'Hangzhou',
        children: [
          {
            value: 'xihu',
            label: 'West Lake',
          },
        ],
      },
    ],
  },
  {
    value: 'jiangsu',
    label: 'Jiangsu',
    children: [
      {
        value: 'nanjing',
        label: 'Nanjing',
        children: [
          {
            value: 'zhonghuamen',
            label: 'Zhong Hua Men',
          },
        ],
      },
    ],
  },
];
export default defineComponent({
  setup() {
    return {
      value: ref<string[]>([]),
      options,
    };
  },
});
</script>
移入展开

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

<template>
  <a-cascader
    v-model:value="value"
    :options="options"
    :display-render="displayRender"
    expand-trigger="hover"
    placeholder="Please select"
  />
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
interface Option {
  value: string;
  label: string;
  children?: Option[];
}
const options: Option[] = [
  {
    value: 'zhejiang',
    label: 'Zhejiang',
    children: [
      {
        value: 'hangzhou',
        label: 'Hangzhou',
        children: [
          {
            value: 'xihu',
            label: 'West Lake',
          },
        ],
      },
    ],
  },
  {
    value: 'jiangsu',
    label: 'Jiangsu',
    children: [
      {
        value: 'nanjing',
        label: 'Nanjing',
        children: [
          {
            value: 'zhonghuamen',
            label: 'Zhong Hua Men',
          },
        ],
      },
    ],
  },
];
export default defineComponent({
  setup() {
    const displayRender = ({ labels }: { labels: string[] }) => {
      return labels[labels.length - 1];
    }; 
    return {
      value: ref<string[]>([]),
      options,
      displayRender,
    };
  },
});
</script>
选择即改变

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

<template>
  <a-cascader v-model:value="value" :options="options" change-on-select />
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
interface Option {
  value: string;
  label: string;
  children?: Option[];
}
const options: Option[] = [
  {
    value: 'zhejiang',
    label: 'Zhejiang',
    children: [
      {
        value: 'hangzhou',
        label: 'Hangzhou',
        children: [
          {
            value: 'xihu',
            label: 'West Lake',
          },
        ],
      },
    ],
  },
  {
    value: 'jiangsu',
    label: 'Jiangsu',
    children: [
      {
        value: 'nanjing',
        label: 'Nanjing',
        children: [
          {
            value: 'zhonghuamen',
            label: 'Zhong Hua Men',
          },
        ],
      },
    ],
  },
];
export default defineComponent({
  setup() {
    return {
      value: ref<string[]>([]),
      options,
    };
  },
});
</script>
Zhejiang /Hangzhou /West Lake ( 752100 )
自定义已选项

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

<template>
  <a-cascader v-model:value="value" :options="options" style="width: 100%">
    <template #displayRender="{ labels, selectedOptions }">
      <span v-for="(label, index) in labels" :key="selectedOptions[index].value">
        <span v-if="index === labels.length - 1">
          {{ label }} (
          <a @click="e => handleAreaClick(e, label, selectedOptions[index])">
            {{ selectedOptions[index].code }}
          </a>
          )
        </span>
        <span v-else>{{ label }} /</span>
      </span>
    </template>
  </a-cascader>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
interface Option {
  value: string;
  label: string;
  children?: Option[];
  code?: number;
  [key: string]: any;
}
const options: Option[] = [
  {
    value: 'zhejiang',
    label: 'Zhejiang',
    children: [
      {
        value: 'hangzhou',
        label: 'Hangzhou',
        children: [
          {
            value: 'xihu',
            label: 'West Lake',
            code: 752100,
          },
        ],
      },
    ],
  },
  {
    value: 'jiangsu',
    label: 'Jiangsu',
    children: [
      {
        value: 'nanjing',
        label: 'Nanjing',
        children: [
          {
            value: 'zhonghuamen',
            label: 'Zhong Hua Men',
            code: 453400,
          },
        ],
      },
    ],
  },
];
export default defineComponent({
  setup() {
    const handleAreaClick = (e: Event, label: string, option: Option) => {
      e.stopPropagation();
      console.log('clicked', label, option);
    }; 
    return {
      value: ref<string[]>(['zhejiang', 'hangzhou', 'xihu']),
      options,
      handleAreaClick,
    };
  },
});
</script>
动态加载选项

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

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

<template>
  <a-cascader
    v-model:value="value"
    :options="options"
    :load-data="loadData"
    placeholder="Please select"
    change-on-select
  />
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
interface Option {
  value: string;
  label: string;
  loading?: boolean;
  isLeaf?: boolean;
  children?: Option[];
}
export default defineComponent({
  setup() {
    const options = ref<Option[]>([
      {
        value: 'zhejiang',
        label: 'Zhejiang',
        isLeaf: false,
      },
      {
        value: 'jiangsu',
        label: 'Jiangsu',
        isLeaf: false,
      },
    ]); 
    const loadData = (selectedOptions: Option[]) => {
      const targetOption = selectedOptions[selectedOptions.length - 1];
      targetOption.loading = true; 
      // load options lazily
      setTimeout(() => {
        targetOption.loading = false;
        targetOption.children = [
          {
            label: `${targetOption.label} Dynamic 1`,
            value: 'dynamic1',
          },
          {
            label: `${targetOption.label} Dynamic 2`,
            value: 'dynamic2',
          },
        ];
        options.value = [...options.value];
      }, 1000);
    }; 
    return {
      value: ref<string[]>([]),
      options,
      loadData,
    };
  },
});
</script>
ab
后缀图标

自定义后缀图标

<template>
  <a-cascader
    v-model:value="value1"
    style="margin-top: 1rem"
    :options="options"
    placeholder="Please select"
  >
    <template #suffixIcon><smile-outlined class="test" /></template>
  </a-cascader>
  <a-cascader
    v-model:value="value2"
    suffix-icon="ab"
    style="margin-top: 1rem"
    :options="options"
    placeholder="Please select"
  />
</template>
<script lang="ts">
import { SmileOutlined } from '@ant-design/icons-vue';
import { defineComponent, ref } from 'vue';
interface Option {
  value: string;
  label: string;
  children?: Option[];
}
const options: Option[] = [
  {
    value: 'zhejiang',
    label: 'Zhejiang',
    children: [
      {
        value: 'hangzhou',
        label: 'Hangzhou',
        children: [
          {
            value: 'xihu',
            label: 'West Lake',
          },
        ],
      },
    ],
  },
  {
    value: 'jiangsu',
    label: 'Jiangsu',
    children: [
      {
        value: 'nanjing',
        label: 'Nanjing',
        children: [
          {
            value: 'zhonghuamen',
            label: 'Zhong Hua Men',
          },
        ],
      },
    ],
  },
];
export default defineComponent({
  components: {
    SmileOutlined,
  },
  setup() {
    return {
      value1: ref<string[]>([]),
      value2: ref<string[]>([]),
      options,
    };
  },
});
</script>
Unselect   Change city
可以自定义显示

切换按钮和结果分开。

<template>
  <span>
    {{ text }} &nbsp;
    <a-cascader v-model:value="value" :options="options" @change="onChange">
      <a href="#">Change city</a>
    </a-cascader>
  </span>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
interface Option {
  value: string;
  label: string;
  children?: Option[];
  code?: number;
  [key: string]: any;
}
const options: Option[] = [
  {
    value: 'zhejiang',
    label: 'Zhejiang',
    children: [
      {
        value: 'hangzhou',
        label: 'Hangzhou',
        children: [
          {
            value: 'xihu',
            label: 'West Lake',
          },
        ],
      },
    ],
  },
  {
    value: 'jiangsu',
    label: 'Jiangsu',
    children: [
      {
        value: 'nanjing',
        label: 'Nanjing',
        children: [
          {
            value: 'zhonghuamen',
            label: 'Zhong Hua Men',
          },
        ],
      },
    ],
  },
]; 
export default defineComponent({
  setup() {
    const value = ref<string[]>([]);
    const text = ref<string>('Unselect'); 
    const onChange = (value: string, selectedOptions: Option[]) => {
      text.value = selectedOptions.map(o => o.label).join(', ');
    }; 
    return {
      value,
      text,
      options,
      onChange,
    };
  },
});
</script>
禁用选项

通过指定 options 里的 disabled 字段。

<template>
  <a-cascader v-model:value="value" :options="options" />
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
interface Option {
  value: string;
  label: string;
  disabled?: boolean;
  children?: Option[];
  code?: number;
  [key: string]: any;
}
const options: Option[] = [
  {
    value: 'zhejiang',
    label: 'Zhejiang',
    children: [
      {
        value: 'hangzhou',
        label: 'Hangzhou',
        children: [
          {
            value: 'xihu',
            label: 'West Lake',
          },
        ],
      },
    ],
  },
  {
    value: 'jiangsu',
    label: 'Jiangsu',
    disabled: true,
    children: [
      {
        value: 'nanjing',
        label: 'Nanjing',
        children: [
          {
            value: 'zhonghuamen',
            label: 'Zhong Hua Men',
          },
        ],
      },
    ],
  },
];
export default defineComponent({
  setup() {
    return {
      value: ref<string[]>([]),
      options,
    };
  },
});
</script>






大小

不同大小的级联选择器。

<template>
  <a-cascader v-model:value="value" size="large" :options="options" />
  <br />
  <br />
  <a-cascader v-model:value="value" :options="options" />
  <br />
  <br />
  <a-cascader v-model:value="value" size="small" :options="options" />
  <br />
  <br />
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
interface Option {
  value: string;
  label: string;
  children?: Option[];
}
const options: Option[] = [
  {
    value: 'zhejiang',
    label: 'Zhejiang',
    children: [
      {
        value: 'hangzhou',
        label: 'Hangzhou',
        children: [
          {
            value: 'xihu',
            label: 'West Lake',
          },
        ],
      },
    ],
  },
  {
    value: 'jiangsu',
    label: 'Jiangsu',
    children: [
      {
        value: 'nanjing',
        label: 'Nanjing',
        children: [
          {
            value: 'zhonghuamen',
            label: 'Zhong Hua Men',
          },
        ],
      },
    ],
  },
];
export default defineComponent({
  setup() {
    return {
      value: ref<string[]>([]),
      options,
    };
  },
});
</script>
自定义字段名

自定义字段名。

<template>
  <a-cascader
    v-model:value="value"
    :field-names="{ label: 'name', value: 'code', children: 'items' }"
    :options="options"
    placeholder="Please select"
  />
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
interface Option {
  code: string;
  name: string;
  disabled?: boolean;
  items?: Option[];
  [key: string]: any;
}
const options: Option[] = [
  {
    code: 'zhejiang',
    name: 'Zhejiang',
    items: [
      {
        code: 'hangzhou',
        name: 'Hangzhou',
        items: [
          {
            code: 'xihu',
            name: 'West Lake',
          },
        ],
      },
    ],
  },
  {
    code: 'jiangsu',
    name: 'Jiangsu',
    items: [
      {
        code: 'nanjing',
        name: 'Nanjing',
        items: [
          {
            code: 'zhonghuamen',
            name: 'Zhong Hua Men',
          },
        ],
      },
    ],
  },
];
export default defineComponent({
  setup() {
    return {
      value: ref<string[]>([]),
      options,
    };
  },
});
</script>

API#

<a-cascader :options="options" v-model:value="value" />
参数 说明 类型 默认值
allowClear 是否支持清除 boolean true
autofocus 自动获取焦点 boolean false
changeOnSelect 当此项为 true 时，点选每级菜单选项值都会发生变化，具体见上面的演示 boolean false
defaultValue 默认的选中项 string[] | number[] []
disabled 禁用 boolean false
displayRender 选择后展示的渲染函数,可使用 #displayRender="{labels, selectedOptions}" ({labels, selectedOptions}) => VNode labels => 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 可选项数据源 Option[] -
placeholder 输入框占位文本 string '请选择'
popupClassName 自定义浮层类名 string -
popupStyle 自定义浮层样式 object {}
popupPlacement 浮层预设位置：bottomLeft bottomRight topLeft topRight Enum bottomLeft
popupVisible 控制浮层显隐 boolean -
showSearch 在选择框中显示搜索框 boolean | object false
size 输入框大小，可选 large default small string default
suffixIcon 自定义的选择框后缀图标 string | VNode | slot -
value(v-model) 指定选中项 string[] | number[] -

showSearch

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

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

事件

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

Option

interface Option {
  value: string | number;
  label?: VNode;
  disabled?: boolean;
  children?: Option[];
}

方法

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

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