Cascader 级联选择

级联选择框。

何时使用

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

代码演示

基本用法
基本用法。

 

<template>
  <f-cascader v-model:value="value" :options="options" placeholder="Please select" />
  &ensp;
  <f-cascader v-model:value="value" :options="options" placeholder="Please select" press-line="级联选择器" />
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
import type { CascaderProps } from 'ant-design-vue'
const options: CascaderProps['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',
          },
        ],
      },
    ],
  },
]
export default defineComponent({
  setup() {
    return {
      value: ref<string[]>([]),
      options,
    }
  },
})
</script>

禁用选项
通过指定 options 里的 disabled 字段。

<template>
  <f-cascader v-model:value="value" placeholder="Please select" :options="options" />
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
import type { CascaderProps } from 'ant-design-vue'
const options: CascaderProps['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',
          },
        ],
      },
    ],
  },
]
export default defineComponent({
  setup() {
    return {
      value: ref<string[]>([]),
      options,
    }
  },
})
</script>

选择即改变
这种交互允许只选中父级选项。

<template>
  <f-cascader v-model:value="value" :options="options" placeholder="Please select" change-on-select />
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
import type { CascaderProps } from 'ant-design-vue'
const options: CascaderProps['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',
          },
        ],
      },
    ],
  },
]
export default defineComponent({
  setup() {
    return {
      value: ref<string[]>([]),
      options,
    }
  },
})
</script>

大小
不同大小的级联选择器。

<template>
  <f-cascader v-model:value="value" placeholder="Please select" size="large" :options="options" />
  <br />
  <br />
  <f-cascader v-model:value="value" placeholder="Please select" :options="options" />
  <br />
  <br />
  <f-cascader v-model:value="value" placeholder="Please select" size="small" :options="options" />
  <br />
  <br />
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
import type { CascaderProps } from 'ant-design-vue'
const options: CascaderProps['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',
          },
        ],
      },
    ],
  },
]
export default defineComponent({
  setup() {
    return {
      value: ref<string[]>([]),
      options,
    }
  },
})
</script>

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

<template>
  <f-cascader
    v-model:value="value"
    :options="options"
    :show-search="{ filter }"
    placeholder="Please select"
  />
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
import type { CascaderProps } from 'ant-design-vue';
import type { ShowSearchType } from 'ant-design-vue/es/cascader';
const options: CascaderProps['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',
          },
        ],
      },
    ],
  },
];
export default defineComponent({
  setup() {
    const filter: ShowSearchType['filter'] = (inputValue, path) => {
      return path.some(option => option.label.toLowerCase().indexOf(inputValue.toLowerCase()) > -1);
    };

    return {
      value: ref<string[]>([]),
      options,
      filter,
    };
  },
});
</script>

多选
一次性选择多个选项。

多选提示框展示选中的内容

<template>
  <f-cascader
    v-model:value="value"
    style="width: 300px"
    multiple
    max-tag-count="responsive"
    :options="options"
    placeholder="Please select"
  ></f-cascader>
  <br />
  <br />
  <div>多选提示框展示选中的内容</div>
  <f-cascader
    v-model:value="value"
    style="width: 100px"
    multiple
    max-tag-count="responsive"
    :options="options"
    placeholder="Please select"
    showMaxTagPlaceholder
    :tooltips="{
      placement: 'bottomLeft',
      color: '#fff',
      textColor: '#333',
      contentHeight: 50,
      align: '{ offset: [0, 0] }',
      destroyTooltipOnHide: false
    }"
  ></f-cascader>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
import type { CascaderProps } from 'ant-design-vue';
const options: CascaderProps['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',
          },
        ],
      },
    ],
  },
];
export default defineComponent({
  setup() {
    return {
      value: ref<string[]>([]),
      options,
    };
  },
});
</script>

## API

参数	说明	类型	默认值	Version
pressLine 新增	组件右上角文本	string
showMaxTagPlaceholder 新增	是否展示超出内容文案	boolean	false
tooltips 新增	Tooltip文字提示组件展示文本，组件参数说明参考Tooltip文字提示组件，新增两个属性 textColor，contentHeight	textColor:string contentHeight:number
allowClear	是否支持清除	boolean	true
autofocus	自动获取焦点	boolean	false
bordered	是否有边框	boolean	true	3.2
clearIcon	自定义的选择框清空图标	slot	-	3.2
changeOnSelect	（单选时生效）当此项为 true 时，点选每级菜单选项值都会发生变化，具体见上面的演示	boolean	false
defaultValue	默认的选中项	string[] | number[]	[]
disabled	禁用	boolean	false
displayRender	选择后展示的渲染函数,可使用 #displayRender="{labels, selectedOptions}"	({labels, selectedOptions}) => VNode	labels => labels.join(' / ')
dropdownClassName	自定义浮层类名	string	-	3.0
dropdownStyle	自定义浮层样式	CSSProperties	{}	3.0
expandIcon	自定义次级菜单展开图标	slot	-	3.0
expandTrigger	次级菜单的展开方式	click | hover	'click'
fieldNames	自定义 options 中 label name children 的字段	object	{ label: 'label', value: 'value', children: 'children' }
getPopupContainer	菜单渲染父节点。默认渲染到 body 上，如果你遇到菜单滚动定位问题，试试修改为滚动的区域，并相对其定位。	Function(triggerNode)	() => document.body
loadData	用于动态加载选项，无法与 showSearch 一起使用	(selectedOptions) => void	-
maxTagCount	最多显示多少个 tag，响应式模式会对性能产生损耗	number | responsive	-	3.0
maxTagPlaceholder	隐藏 tag 时显示的内容	v-slot | function(omittedValues)	-	3.0
multiple	支持多选节点	boolean	-	3.0
notFoundContent	当下拉列表为空时显示的内容	string | slot	'Not Found'
open	控制浮层显隐	boolean	-	3.0
options	可选项数据源	Option[]	-
placeholder	输入框占位文本	string	'请选择'
placement	浮层预设位置	bottomLeft | bottomRight | topLeft | topRight	bottomLeft	3.0
removeIcon	自定义的多选框清除图标	slot	-	3.2
searchValue	设置搜索的值，需要与 showSearch 配合使用	string	-	3.0
showSearch	在选择框中显示搜索框	boolean | object	false
size	输入框大小	large | default | small	default
suffixIcon	自定义的选择框后缀图标	string | VNode | slot	-
tagRender	自定义 tag 内容，多选时生效	slot	-	3.0
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	-
dropdownVisibleChange	显示/隐藏浮层的回调	(value) => void	-	3.0
search	监听搜索，返回输入的值	(value) => void	-	3.0

Option

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

方法

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