Appearance

Cascader 级联选择 ​

级联选择框。

代码演示 ​

基本用法 ​

省市区级联。

Please select
vue
<template>
  <a-cascader v-model:value="value" :options="options" placeholder="Please select" />
</template>
<script setup>
import { ref } from 'vue';
const options = [
  {
    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',
          },
        ],
      },
    ],
  },
];
const value = ref([]);
</script>

自定义显示 ​

切换按钮和结果分开。

Unselect   Change city
vue
<template>
  <span>
    {{ text }} &nbsp;
    <a-cascader
      v-model:value="value"
      placeholder="Please select"
      :options="options"
      @change="onChange"
    >
      <a href="#">Change city</a>
    </a-cascader>
  </span>
</template>
<script setup>
import { ref } from 'vue';
const options = [
  {
    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',
          },
        ],
      },
    ],
  },
];
const value = ref([]);
const text = ref('Unselect');
const onChange = (_value, selectedOptions) => {
  text.value = selectedOptions.map(o => o.label).join(', ');
};
</script>

移入展开 ​

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

Please select
vue
<template>
  <a-cascader
    v-model:value="value"
    :options="options"
    expand-trigger="hover"
    placeholder="Please select"
  />
</template>
<script setup>
import { ref } from 'vue';
const options = [
  {
    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',
          },
        ],
      },
    ],
  },
];
const value = ref([]);
</script>

禁用选项 ​

通过指定 options 里的 disabled 字段。

Please select
vue
<template>
  <a-cascader v-model:value="value" placeholder="Please select" :options="options" />
</template>
<script setup>
import { ref } from 'vue';
const options = [
  {
    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',
          },
        ],
      },
    ],
  },
];
const value = ref([]);
</script>

选择即改变 ​

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

Please select
vue
<template>
  <a-cascader
    v-model:value="value"
    :options="options"
    placeholder="Please select"
    change-on-select
  />
</template>
<script setup>
import { ref } from 'vue';
const options = [
  {
    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',
          },
        ],
      },
    ],
  },
];
const value = ref([]);
</script>

自定义已选项 ​

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

Zhejiang /Hangzhou /West Lake ( 752100 )
vue
<template>
  <a-cascader
    v-model:value="value"
    placeholder="Please select"
    :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 setup>
import { ref } from 'vue';
const options = [
  {
    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,
          },
        ],
      },
    ],
  },
];
const handleAreaClick = (e, label, option) => {
  e.stopPropagation();
  console.log('clicked', label, option);
};
const value = ref(['zhejiang', 'hangzhou', 'xihu']);
</script>

搜索 ​

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

Please select
vue
<template>
  <a-cascader
    v-model:value="value"
    :options="options"
    :show-search="{ filter }"
    placeholder="Please select"
  />
</template>
<script setup>
import { ref } from 'vue';
const options = [
  {
    value: 'zhejiang',
    label: 'Zhejiang',
    children: [
      {
        value: 'hangzhou',
        label: 'Hangzhou',
        children: [
          {
            value: 'xihu',
            label: 'West Lake',
          },
          {
            value: 'xiasha',
            label: 'Xia Sha',
            disabled: true,
          },
        ],
      },
    ],
  },
  {
    value: 'jiangsu',
    label: 'Jiangsu',
    children: [
      {
        value: 'nanjing',
        label: 'Nanjing',
        children: [
          {
            value: 'zhonghuamen',
            label: 'Zhong Hua men',
          },
        ],
      },
    ],
  },
];
const filter = (inputValue, path) => {
  return path.some(option => option.label.toLowerCase().indexOf(inputValue.toLowerCase()) > -1);
};
const value = ref([]);
</script>

动态加载选项 ​

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

Please select
vue
<template>
  <a-cascader
    v-model:value="value"
    :options="options"
    :load-data="loadData"
    placeholder="Please select"
    change-on-select
  />
</template>
<script setup>
import { ref } from 'vue';
const options = ref([
  {
    value: 'zhejiang',
    label: 'Zhejiang',
    isLeaf: false,
  },
  {
    value: 'jiangsu',
    label: 'Jiangsu',
    isLeaf: false,
  },
]);
const loadData = selectedOptions => {
  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);
};
const value = ref([]);
</script>

多选 ​

一次性选择多个选项。

Cascader.SHOW_PARENT

Please select

Cascader.SHOW_CHILD

Please select
vue
<template>
  <a-space direction="vertical" style="width: 100%">
    <h4>Cascader.SHOW_PARENT</h4>
    <a-cascader
      v-model:value="value"
      style="width: 100%"
      multiple
      max-tag-count="responsive"
      :options="options"
      placeholder="Please select"
    ></a-cascader>
    <h4>Cascader.SHOW_CHILD</h4>
    <a-cascader
      v-model:value="value"
      style="width: 100%"
      multiple
      max-tag-count="responsive"
      :options="options"
      placeholder="Please select"
      :show-checked-strategy="Cascader.SHOW_CHILD"
    ></a-cascader>
  </a-space>
</template>
<script setup>
import { ref } from 'vue';
const options = [
  {
    label: 'Light',
    value: 'light',
    children: new Array(20).fill(null).map((_, index) => ({
      label: `Number ${index}`,
      value: index,
    })),
  },
  {
    label: 'Bamboo',
    value: 'bamboo',
    children: [
      {
        label: 'Little',
        value: 'little',
        children: [
          {
            label: 'Toy Fish',
            value: 'fish',
          },
          {
            label: 'Toy Cards',
            value: 'cards',
          },
          {
            label: 'Toy Bird',
            value: 'bird',
          },
        ],
      },
    ],
  },
];
const value = ref([]);
</script>

API ​

html
<a-cascader :options="options" v-model:value="value" />
参数说明类型默认值
allowClear是否支持清除booleantrue
autofocus自动获取焦点booleanfalse
bordered是否有边框booleantrue
clearIcon自定义的选择框清空图标slot-
changeOnSelect（单选时生效）当此项为 true 时，点选每级菜单选项值都会发生变化，具体见上面的演示booleanfalse
defaultValue默认的选中项string[] | number[][]
disabled禁用booleanfalse
displayRender选择后展示的渲染函数,可使用 #displayRender="{labels, selectedOptions}"({labels, selectedOptions}) => VNodelabels => labels.join(' / ')
popupClassName自定义浮层类名string-
dropdownStyle自定义浮层样式CSSProperties{}
expandIcon自定义次级菜单展开图标slot-
expandTrigger次级菜单的展开方式click | hover'click'
fieldNames自定义 options 中 label value children 的字段object{ label: 'label', value: 'value', children: 'children' }
getPopupContainer菜单渲染父节点。默认渲染到 body 上，如果你遇到菜单滚动定位问题，试试修改为滚动的区域，并相对其定位。Function(triggerNode)() => document.body
loadData用于动态加载选项，无法与 showSearch 一起使用(selectedOptions) => void-
maxTagCount最多显示多少个 tag，响应式模式会对性能产生损耗number | responsive-
maxTagPlaceholder隐藏 tag 时显示的内容v-slot | function(omittedValues)-
multiple支持多选节点boolean-
notFoundContent当下拉列表为空时显示的内容string | slot'Not Found'
open控制浮层显隐boolean-
options可选项数据源Option[]-
placeholder输入框占位文本string'请选择'
placement浮层预设位置bottomLeft | bottomRight | topLeft | topRightbottomLeft
showCheckedStrategy定义选中项回填的方式。Cascader.SHOW_CHILD: 只显示选中的子节点。Cascader.SHOW_PARENT: 只显示父节点（当父节点下所有子节点都选中时）。Cascader.SHOW_PARENT | Cascader.SHOW_CHILDCascader.SHOW_PARENT
removeIcon自定义的多选框清除图标slot-
searchValue设置搜索的值，需要与 showSearch 配合使用string-
showSearch在选择框中显示搜索框boolean | objectfalse
status设置校验状态'error' | 'warning'-
size输入框大小large | default | smalldefault
suffixIcon自定义的选择框后缀图标string | VNode | slot-
tagRender自定义 tag 内容，多选时生效slot-
value(v-model)指定选中项string[] | number[]-

showSearch ​

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

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

事件 ​

事件名称说明回调参数
change选择完成后的回调(value, selectedOptions) => void
dropdownVisibleChange显示/隐藏浮层的回调(value) => void
search监听搜索，返回输入的值(value) => void

Option ​

ts
interface Option {
  value: string | number;
  label?: any;
  disabled?: boolean;
  children?: Option[];
  // 标记是否为叶子节点，设置了 `loadData` 时有效
  // 设为 `false` 时会强制标记为父节点，即使当前节点没有 children，也会显示展开图标
  isLeaf?: boolean;
}

方法 ​

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