Cascader 级联选择

级联选择框。

何时使用

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

代码演示

基本

省市区级联。

Cascader级联选择 - 图1

  1. ​
  2. import React from 'react';
  3. import ReactDOM from 'react-dom';
  4. import { Cascader } from 'choerodon-ui';
  5. ​
  6. const options = [{
  7.   value: 'zhejiang',
  8.   label: 'Zhejiang',
  9.   children: [{
  10.     value: 'hangzhou',
  11.     label: 'Hangzhou',
  12.     children: [{
  13.       value: 'xihu',
  14.       label: 'West Lake',
  15.     }],
  16.   }],
  17. }, {
  18.   value: 'jiangsu',
  19.   label: 'Jiangsu',
  20.   children: [{
  21.     value: 'nanjing',
  22.     label: 'Nanjing',
  23.     children: [{
  24.       value: 'zhonghuamen',
  25.       label: 'Zhong Hua Men',
  26.     }],
  27.   }],
  28. }];
  29. ​
  30. function onChange(value) {

默认值

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

Cascader级联选择 - 图2

  1. ​
  2. import React from 'react';
  3. import ReactDOM from 'react-dom';
  4. import { Cascader } from 'choerodon-ui';
  5. ​
  6. const options = [{
  7.   value: 'zhejiang',
  8.   label: 'Zhejiang',
  9.   children: [{
  10.     value: 'hangzhou',
  11.     label: 'Hangzhou',
  12.     children: [{
  13.       value: 'xihu',
  14.       label: 'West Lake',
  15.     }],
  16.   }],
  17. }, {
  18.   value: 'jiangsu',
  19.   label: 'Jiangsu',
  20.   children: [{
  21.     value: 'nanjing',
  22.     label: 'Nanjing',
  23.     children: [{
  24.       value: 'zhonghuamen',
  25.       label: 'Zhong Hua Men',
  26.     }],
  27.   }],
  28. }];
  29. ​

可以自定义显示

切换按钮和结果分开。

Cascader级联选择 - 图3

  1. ​
  2. import React from 'react';
  3. import ReactDOM from 'react-dom';
  4. import { Cascader } from 'choerodon-ui';
  5. ​
  6. const options = [{
  7.   value: 'zhejiang',
  8.   label: 'Zhejiang',
  9.   children: [{
  10.     value: 'hangzhou',
  11.     label: 'Hangzhou',
  12.   }],
  13. }, {
  14.   value: 'jiangsu',
  15.   label: 'Jiangsu',
  16.   children: [{
  17.     value: 'nanjing',
  18.     label: 'Nanjing',
  19.   }],
  20. }];
  21. ​
  22. class CitySwitcher extends React.Component {
  23.   state = {
  24.     text: 'Unselect',
  25.   };
  26. ​
  27.   onChange = (value, selectedOptions) => {
  28.     this.setState({
  29.       text: selectedOptions.map(o => o.label).join(', '),
  30.     });

移入展开

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

Cascader级联选择 - 图4

  1. ​
  2. import React from 'react';
  3. import ReactDOM from 'react-dom';
  4. import { Cascader } from 'choerodon-ui';
  5. ​
  6. const options = [{
  7.   value: 'zhejiang',
  8.   label: 'Zhejiang',
  9.   children: [{
  10.     value: 'hangzhou',
  11.     label: 'Hangzhou',
  12.     children: [{
  13.       value: 'xihu',
  14.       label: 'West Lake',
  15.     }],
  16.   }],
  17. }, {
  18.   value: 'jiangsu',
  19.   label: 'Jiangsu',
  20.   children: [{
  21.     value: 'nanjing',
  22.     label: 'Nanjing',
  23.     children: [{
  24.       value: 'zhonghuamen',
  25.       label: 'Zhong Hua Men',
  26.     }],
  27.   }],
  28. }];
  29. ​
  30. function onChange(value) {
  31.   console.log(value);
  32. }
  33. ​
  34. // Just show the latest item.
  35. function displayRender(label) {
  36.   return label[label.length - 1];

禁用选项

通过指定 options 里的 disabled 字段。

Cascader级联选择 - 图5

  1. ​
  2. import React from 'react';
  3. import ReactDOM from 'react-dom';
  4. import { Cascader } from 'choerodon-ui';
  5. ​
  6. const options = [{
  7.   value: 'zhejiang',
  8.   label: 'Zhejiang',
  9.   children: [{
  10.     value: 'hangzhou',
  11.     label: 'Hangzhou',
  12.     children: [{
  13.       value: 'xihu',
  14.       label: 'West Lake',
  15.     }],
  16.   }],
  17. }, {
  18.   value: 'jiangsu',
  19.   label: 'Jiangsu',
  20.   disabled: true,
  21.   children: [{
  22.     value: 'nanjing',
  23.     label: 'Nanjing',
  24.     children: [{
  25.       value: 'zhonghuamen',
  26.       label: 'Zhong Hua Men',
  27.     }],
  28.   }],
  29. }];
  30. ​

选择即改变

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

Cascader级联选择 - 图6

  1. ​
  2. import React from 'react';
  3. import ReactDOM from 'react-dom';
  4. import { Cascader } from 'choerodon-ui';
  5. ​
  6. const options = [{
  7.   value: 'zhejiang',
  8.   label: 'Zhejiang',
  9.   children: [{
  10.     value: 'hangzhou',
  11.     label: 'Hanzhou',
  12.     children: [{
  13.       value: 'xihu',
  14.       label: 'West Lake',
  15.     }],
  16.   }],
  17. }, {
  18.   value: 'jiangsu',
  19.   label: 'Jiangsu',
  20.   children: [{
  21.     value: 'nanjing',
  22.     label: 'Nanjing',
  23.     children: [{
  24.       value: 'zhonghuamen',
  25.       label: 'Zhong Hua Men',
  26.     }],
  27.   }],
  28. }];
  29. ​
  30. function onChange(value) {

大小

不同大小的级联选择器。

Cascader级联选择 - 图7

  1. ​
  2. import React from 'react';
  3. import ReactDOM from 'react-dom';
  4. import { Cascader } from 'choerodon-ui';
  5. ​
  6. const options = [{
  7.   value: 'zhejiang',
  8.   label: 'Zhejiang',
  9.   children: [{
  10.     value: 'hangzhou',
  11.     label: 'Hangzhou',
  12.     children: [{
  13.       value: 'xihu',
  14.       label: 'West Lake',
  15.     }],
  16.   }],
  17. }, {
  18.   value: 'jiangsu',
  19.   label: 'Jiangsu',
  20.   children: [{
  21.     value: 'nanjing',
  22.     label: 'Nanjing',
  23.     children: [{
  24.       value: 'zhonghuamen',
  25.       label: 'Zhong Hua Men',
  26.     }],
  27.   }],
  28. }];
  29. ​
  30. function onChange(value) {

自定义已选项

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

Cascader级联选择 - 图8

  1. ​
  2. import React from 'react';
  3. import ReactDOM from 'react-dom';
  4. import { Cascader } from 'choerodon-ui';
  5. ​
  6. const options = [{
  7.   value: 'zhejiang',
  8.   label: 'Zhejiang',
  9.   children: [{
  10.     value: 'hangzhou',
  11.     label: 'Hangzhou',
  12.     children: [{
  13.       value: 'xihu',
  14.       label: 'West Lake',
  15.       code: 752100,
  16.     }],
  17.   }],
  18. }, {
  19.   value: 'jiangsu',
  20.   label: 'Jiangsu',
  21.   children: [{
  22.     value: 'nanjing',
  23.     label: 'Nanjing',
  24.     children: [{
  25.       value: 'zhonghuamen',
  26.       label: 'Zhong Hua Men',
  27.       code: 453400,
  28.     }],
  29.   }],
  30. }];

搜索

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

Cascader[showSearch] 暂不支持服务端搜索

Cascader级联选择 - 图9

  1. ​
  2. import React from 'react';
  3. import ReactDOM from 'react-dom';
  4. import { Cascader } from 'choerodon-ui';
  5. ​
  6. const options = [
  7.   {
  8.     value: 'zhejiang',
  9.     label: 'Zhejiang',
  10.     children: [
  11.       {
  12.         value: 'hangzhou',
  13.         label: 'Hangzhou',
  14.         children: [
  15.           {
  16.             value: 'xihu',
  17.             label: 'West Lake',
  18.           },
  19.           {
  20.             value: 'xiasha',
  21.             label: 'Xia Sha',
  22.             disabled: true,
  23.           },
  24.         ],
  25.       },
  26.     ],
  27.   },
  28.   {
  29.     value: 'jiangsu',
  30.     label: 'Jiangsu',

动态加载选项

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

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

Cascader级联选择 - 图10

  1. ​
  2. import React from 'react';
  3. import ReactDOM from 'react-dom';
  4. import { Cascader } from 'choerodon-ui';
  5. ​
  6. const options = [{
  7.   value: 'zhejiang',
  8.   label: 'Zhejiang',
  9.   isLeaf: false,
  10. }, {
  11.   value: 'jiangsu',
  12.   label: 'Jiangsu',
  13.   isLeaf: false,
  14. }];
  15. ​
  16. class LazyOptions extends React.Component {
  17.   state = {
  18.     options,
  19.   };
  20. ​
  21.   onChange = (value, selectedOptions) => {
  22.     console.log(value, selectedOptions);
  23.   }
  24. ​
  25.   loadData = (selectedOptions) => {
  26.     const targetOption = selectedOptions[selectedOptions.length - 1];
  27.     targetOption.loading = true;
  28. ​
  29.     // load options lazily
  30.     setTimeout(() => {

单栏选择

每次选项都只可以选择一个menu弹出，可以实现大量数据的选择情况。可以通过头部来切换选择层级

Cascader级联选择 - 图11

  1. ​
  2. import React from 'react';
  3. import ReactDOM from 'react-dom';
  4. import { Cascader } from 'choerodon-ui';
  5. ​
  6. const options = [{
  7.   value: 'chengdu',
  8.   label: '成都',
  9.   isLeaf: false,
  10. }, {
  11.   value: 'lanjin',
  12.   label: '南京',
  13.   isLeaf: false,
  14. },{
  15.   value: 'LA',
  16.   label: 'LA',
  17.   isLeaf: false,
  18. }, {
  19.   value: 'Boston',
  20.   label: 'Boston',
  21.   isLeaf: false,
  22. }];
  23. ​
  24. class LazyOptions extends React.Component {
  25.   state = {
  26.     options,
  27.   };
  28. ​
  29.   onChange = (value, selectedOptions) => {
  30.     console.log(value, selectedOptions)

API

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

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

参数说明类型默认值
filter接收 inputValue path 两个参数，当 path 符合筛选条件时，应返回 true，反之则返回 false。(inputValue, path) => boolean
matchInputWidth搜索结果列表是否与输入框同宽boolean
render用于渲染 filter 后的选项(inputValue, path) => ReactNode
sort用于排序 filter 后的选项(a, b, inputValue) =>

menuMode 为 single，其中可以添加的配置：

参数说明类型默认值
singleMenuStyle由于渲染在body下可以方便按照业务配置弹出框的大小CSSProperties
singleMenuItemStyle由于渲染在body下可以方便按照业务配置超出大小样式和最小宽度等CSSProperties
singlePleaseRender设置需要的提示配置({key,className,text}) => ReactElement
singleMenuItemRender头部可以渲染出想要的tab样子(title) => ReactElement

方法

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

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