CascaderSelect 级联选择

如果项目中使用的是 0.x 版本的基础组件（@icedesign/base, @ali/ice, @alife/next），请在左侧导航顶部切换组件版本。

安装方法

  1. 在命令行中执行以下命令npm install @alifd/next@latest -S

开发指南

何时使用

级联选择由选择器和级联组成。把级联组件以弹层的方式隐藏，多用于表单场景。

API

CascaderSelect

参数说明类型默认值
size选择框大小可选值:'small', 'medium', 'large'Enum'medium'
placeholder选择框占位符String-
disabled是否禁用Booleanfalse
hasArrow是否有下拉箭头Booleantrue
hasBorder是否有边框Booleantrue
hasClear是否有清除按钮Booleanfalse
label自定义内联 labelReactNode-
readOnly是否只读，只读模式下可以展开弹层但不能选Boolean-
dataSource数据源，结构可参考下方说明Array<Object>[]
defaultValue（非受控）默认值String/Array<String>null
value（受控）当前值String/Array<String>-
onChange选中值改变时触发的回调函数签名:Function(value: String/Array, data: Object/Array, extra: Object) => void参数:value: {String/Array} 选中的值，单选时返回单个值，多选时返回数组data: {Object/Array} 选中的数据，包括 value 和 label，单选时返回单个值，多选时返回数组，父子节点选中关联时，同时选中，只返回父节点extra: {Object} 额外参数extra.selectedPath: {Array} 单选时选中的数据的路径extra.checked: {Boolean} 多选时当前的操作是选中还是取消选中extra.currentData: {Object} 多选时当前操作的数据extra.checkedData: {Array} 多选时所有被选中的数据extra.indeterminateData: {Array} 多选时半选的数据Function-
defaultExpandedValue默认展开值，如果不设置，组件内部会根据 defaultValue/value 进行自动设置Array<String>-
expandTriggerType展开触发的方式可选值:'click', 'hover'Enum'click'
useVirtual是否开启虚拟滚动Booleanfalse
multiple是否多选Booleanfalse
changeOnSelect是否选中即发生改变, 该属性仅在单选模式下有效Booleanfalse
canOnlyCheckLeaf是否只能勾选叶子项的checkbox，该属性仅在多选模式下有效Booleanfalse
checkStrictly父子节点是否选中不关联Booleanfalse
listStyle每列列表样式对象Object-
listClassName每列列表类名String-
displayRender选择框单选时展示结果的自定义渲染函数签名:Function(label: Array) => ReactNode参数:label: {Array} 选中路径的文本数组返回值:{ReactNode} 渲染在选择框中的内容Function单选时：labelPath => labelPath.join(' / ')；多选时：labelPath => labelPathlabelPath.length - 1
itemRender渲染 item 内容的方法签名:Function(item: Object) => ReactNode参数:item: {Object} 渲染节点的item返回值:{ReactNode} item nodeFunction-
showSearch是否显示搜索框Booleanfalse
filter自定义搜索函数签名:Function(searchValue: String, path: Array) => Boolean参数:searchValue: {String} 搜索的关键字path: {Array} 节点路径返回值:{Boolean} 是否匹配Function根据路径所有节点的文本值模糊匹配
resultRender搜索结果自定义渲染函数签名:Function(searchValue: String, path: Array) => ReactNode参数:searchValue: {String} 搜索的关键字path: {Array} 匹配到的节点路径返回值:{ReactNode} 渲染的内容Function按照节点文本 a / b / c 的模式渲染
resultAutoWidth搜索结果列表是否和选择框等宽Booleantrue
notFoundContent无数据时显示内容ReactNode'Not Found'
loadData异步加载数据函数签名:Function(data: Object) => void参数:data: {Object} 当前点击异步加载的数据Function-
header自定义下拉框头部ReactNode-
footer自定义下拉框底部ReactNode-
defaultVisible初始下拉框是否显示Booleanfalse
visible当前下拉框是否显示Boolean-
onVisibleChange下拉框显示或关闭时触发事件的回调函数签名:Function(visible: Boolean, type: String) => void参数:visible: {Boolean} 是否显示type: {String} 触发显示关闭的操作类型, fromTrigger 表示由trigger的点击触发； docClick 表示由document的点击触发Function() => {}
popupStyle下拉框自定义样式对象Object-
popupClassName下拉框样式自定义类名String-
popupContainer下拉框挂载的容器节点String/Function-
popupProps透传到 Popup 的属性对象Object{}
followTrigger是否跟随滚动Boolean-
<!— api-extra-start —>### dataSource数据结构#
  1. const dataSource = [{    value: '2974',    label: '西安',    children: [        { value: '2975', label: '西安市', disabled: true },        { value: '2976', label: '高陵县', checkboxDisabled: true },        { value: '2977', label: '蓝田县' },        { value: '2978', label: '户县' },        { value: '2979', label: '周至县' },        { value: '4208', label: '灞桥区' },        { value: '4209', label: '长安区' },        { value: '4210', label: '莲湖区' },        { value: '4211', label: '临潼区' },        { value: '4212', label: '未央区' },        { value: '4213', label: '新城区' },        { value: '4214', label: '阎良区' },        { value: '4215', label: '雁塔区' },        { value: '4388', label: '碑林区' },        { value: '610127', label: '其它区' }    ]}];
数组中 Item 的自定义属性也会被透传到 onChange 函数的 data 参数中。<!— api-extra-end —>## ARIA and KeyBoard#
按键说明
Up Arrow获取同级当前项前一项焦点
Down Arrow获取同级当前项后一项焦点
Left Arrow进入当前项的子元素，并获取第一个子元素为焦点
Right Arrow返回当前项的父元素并获取焦点
Enter打开目录或选择当前项
Esc关闭目录
SPACE选择当前项

代码示例

基本使用

展示基本的单选用法。

CascaderSelect 级联选择 - 图1

查看源码在线预览

  1. import { CascaderSelect } from '@alifd/next';
  3. class Demo extends React.Component {
  4.     constructor(props) {
  5.         super(props);
  7.         this.state = {
  8.             data: []
  9.         };
  11.         this.handleChange = this.handleChange.bind(this);
  12.     }
  14.     componentDidMount() {
  15.         fetch('https://os.alipayobjects.com/rmsportal/ODDwqcDFTLAguOvWEolX.json')
  16.             .then(response => response.json())
  17.             .then(data => {
  18.                 data[1].disabled = true;
  19.                 this.setState({ data });
  20.             })
  21.             .catch(e => console.log(e));
  22.     }
  24.     handleChange(value, data, extra) {
  25.         console.log(value, data, extra);
  26.     }
  28.     render() {
  29.         return <CascaderSelect style={{ width: '302px' }} dataSource={this.state.data} onChange={this.handleChange} />;
  30.     }
  31. }
  33. ReactDOM.render(<Demo />, mountNode);

展开触发行为

展示可通过 expandTriggerType 来设置不同的展开触发行为，支持 click 和 hover，默认值为 click。

CascaderSelect 级联选择 - 图2

查看源码在线预览

  1. import { Radio, CascaderSelect } from '@alifd/next';
  3. const RadioGroup = Radio.Group;
  5. class Demo extends React.Component {
  6.     constructor(props) {
  7.         super(props);
  9.         this.state = {
  10.             triggerType: 'click',
  11.             data: []
  12.         };
  14.         this.handleChange = this.handleChange.bind(this);
  15.         this.handleTriggerTypeChange = this.handleTriggerTypeChange.bind(this);
  16.     }
  18.     componentDidMount() {
  19.         fetch('https://os.alipayobjects.com/rmsportal/ODDwqcDFTLAguOvWEolX.json')
  20.             .then(response => response.json())
  21.             .then(data => this.setState({ data }))
  22.             .catch(e => console.log(e));
  23.     }
  25.     handleChange(value, data, extra) {
  26.         console.log(value, data, extra);
  27.     }
  29.     handleTriggerTypeChange(triggerType) {
  30.         this.setState({
  31.             triggerType
  32.         });
  33.     }
  35.     render() {
  36.         return (
  37.             <div>
  38.                 <div className="trigger-check">
  39.                     Expand trigger type:
  40.                     <RadioGroup dataSource={['click', 'hover']} value={this.state.triggerType} onChange={this.handleTriggerTypeChange} />
  41.                 </div>
  43.                 <CascaderSelect style={{ width: '302px' }} expandTriggerType={this.state.triggerType} dataSource={this.state.data} onChange={this.handleChange} />
  44.             </div>
  45.         );
  46.     }
  47. }
  49. ReactDOM.render(<Demo />, mountNode);
  1. .trigger-check {
  2.     margin-bottom: 10px;
  3.     font-size: 14px;
  4.     color: #666;
  5. }
  7. .trigger-check .next-radio-group {
  8.     margin-left: 10px;
  9. }

多选

展示基本的多选用法。

CascaderSelect 级联选择 - 图3

查看源码在线预览

  1. import { CascaderSelect } from '@alifd/next';
  3. class Demo extends React.Component {
  4.     constructor(props) {
  5.         super(props);
  7.         this.state = {
  8.             data: []
  9.         };
  11.         this.handleChange = this.handleChange.bind(this);
  12.     }
  14.     componentDidMount() {
  15.         fetch('https://os.alipayobjects.com/rmsportal/ODDwqcDFTLAguOvWEolX.json')
  16.             .then(response => response.json())
  17.             .then(data => {
  18.                 data[1].disabled = true;
  19.                 data[2].checkboxDisabled = true;
  20.                 this.setState({ data });
  21.             })
  22.             .catch(e => console.log(e));
  23.     }
  25.     handleChange(value, data, extra) {
  26.         console.log(value, data, extra);
  27.     }
  29.     render() {
  30.         return <CascaderSelect style={{ width: '302px' }} multiple dataSource={this.state.data} onChange={this.handleChange} />;
  31.     }
  32. }
  34. ReactDOM.render(<Demo />, mountNode);
  1. .cascader-value {
  2.     width: 500px;
  3.     margin-bottom: 10px;
  4.     font-size: 14px;
  5.     color: #666;
  6. }

设置是否只能选择叶子项

展示受控单选以及是否选择即改变。

CascaderSelect 级联选择 - 图4

查看源码在线预览

  1. import { Checkbox, CascaderSelect } from '@alifd/next';
  3. class Demo extends React.Component {
  4.     constructor(props) {
  5.         super(props);
  7.         this.state = {
  8.             value: null,
  9.             changeOnSelect: false,
  10.             data: []
  11.         };
  13.         this.handleCheck = this.handleCheck.bind(this);
  14.         this.handleChange = this.handleChange.bind(this);
  15.     }
  17.     componentDidMount() {
  18.         fetch('https://os.alipayobjects.com/rmsportal/ODDwqcDFTLAguOvWEolX.json')
  19.             .then(response => response.json())
  20.             .then(data => this.setState({ data, value: '2975' }))
  21.             .catch(e => console.log(e));
  22.     }
  24.     handleCheck() {
  25.         this.setState({
  26.             changeOnSelect: !this.state.changeOnSelect,
  27.             value: null
  28.         });
  29.     }
  31.     handleChange(value, data, extra) {
  32.         console.log(value, data, extra);
  34.         this.setState({
  35.             value
  36.         });
  37.     }
  39.     render() {
  40.         return (
  41.             <div className="control-single-demo">
  42.                 <label className="change-check">
  43.                     <Checkbox value={!this.state.changeOnSelect} onChange={this.handleCheck} />
  44.                     <span className="change-text">Enable changeOnSelect</span>
  45.                 </label>
  46.                 <CascaderSelect style={{ width: '302px' }} changeOnSelect={this.state.changeOnSelect} value={this.state.value} dataSource={this.state.data} onChange={this.handleChange} />
  47.             </div>
  48.         );
  49.     }
  50. }
  52. ReactDOM.render(<Demo />, mountNode);
  1. .control-single-demo .change-check {
  2.     display: block;
  3.     margin-bottom: 10px;
  4. }
  6. .control-single-demo .change-text {
  7.     display: inline-block;
  8.     margin-left: 10px;
  9.     vertical-align: middle;
  10.     color: #666;
  11.     font-size: 14px;
  12. }

设置父子节点选中是否关联

展示受控多选以及是否开启严格受控父子节点选中不再关联的用法。

CascaderSelect 级联选择 - 图5

查看源码在线预览

  1. import { Checkbox, CascaderSelect } from '@alifd/next';
  3. class Demo extends React.Component {
  4.     constructor(props) {
  5.         super(props);
  7.         this.state = {
  8.             value: [],
  9.             data: [],
  10.             checkStrictly: false
  11.         };
  13.         this.handleCheck = this.handleCheck.bind(this);
  14.         this.handleChange = this.handleChange.bind(this);
  15.     }
  17.     componentDidMount() {
  18.         fetch('https://os.alipayobjects.com/rmsportal/ODDwqcDFTLAguOvWEolX.json')
  19.             .then(response => response.json())
  20.             .then(data => this.setState({ data, value: ['2975'] }))
  21.             .catch(e => console.log(e));
  22.     }
  24.     handleCheck() {
  25.         this.setState({
  26.             checkStrictly: !this.state.checkStrictly,
  27.             value: []
  28.         });
  29.     }
  31.     handleChange(value, data, extra) {
  32.         console.log(value, data, extra);
  34.         this.setState({
  35.             value
  36.         });
  37.     }
  39.     render() {
  40.         return (
  41.             <div className="control-multiple-demo">
  42.                 <label className="strictly-check">
  43.                     <Checkbox value={this.state.checkStrictly} onChange={this.handleCheck} />
  44.                     <span className="strictly-text">Enable checkStrictly</span>
  45.                 </label>
  46.                 <CascaderSelect style={{ width: '302px' }} multiple checkStrictly={this.state.checkStrictly} value={this.state.value} dataSource={this.state.data} onChange={this.handleChange} />
  47.             </div>
  48.         );
  49.     }
  50. }
  52. ReactDOM.render(<Demo />, mountNode);
  1. .control-multiple-demo .strictly-check {
  2.     display: block;
  3.     margin-bottom: 10px;
  4. }
  6. .control-multiple-demo .strictly-text {
  7.     display: inline-block;
  8.     margin-left: 10px;
  9.     vertical-align: middle;
  10.     color: #666;
  11.     font-size: 14px;
  12. }

搜索

通过设置 showSearch 为 true，可以开启组件的搜索功能。

CascaderSelect 级联选择 - 图6

查看源码在线预览

  1. import { Checkbox, CascaderSelect } from '@alifd/next';
  3. class Demo extends React.Component {
  4.     constructor(props) {
  5.         super(props);
  7.         this.state = {
  8.             value: [],
  9.             data: [],
  10.             multiple: false
  11.         };
  13.         this.handleCheck = this.handleCheck.bind(this);
  14.         this.handleChange = this.handleChange.bind(this);
  15.     }
  17.     componentDidMount() {
  18.         fetch('https://os.alipayobjects.com/rmsportal/ODDwqcDFTLAguOvWEolX.json')
  19.             .then(response => response.json())
  20.             .then(data => this.setState({ data, value: ['2975'] }))
  21.             .catch(e => console.log(e));
  22.     }
  24.     handleCheck() {
  25.         this.setState({
  26.             multiple: !this.state.multiple,
  27.             value: []
  28.         });
  29.     }
  31.     handleChange(value, data, extra) {
  32.         console.log(value, data, extra);
  34.         this.setState({
  35.             value
  36.         });
  37.     }
  39.     render() {
  40.         return (
  41.             <div className="search-demo">
  42.                 <label className="multiple-check">
  43.                     <Checkbox value={this.state.multiple} onChange={this.handleCheck} />
  44.                     <span className="multiple-text">Multiple select</span>
  45.                 </label>
  46.                 <CascaderSelect style={{ width: '302px' }} showSearch multiple={this.state.multiple} value={this.state.value} dataSource={this.state.data} onChange={this.handleChange} />
  47.             </div>
  48.         );
  49.     }
  50. }
  52. ReactDOM.render(<Demo />, mountNode);
  1. .search-demo .multiple-check {
  2.     display: block;
  3.     margin-bottom: 10px;
  4. }
  6. .search-demo .multiple-text {
  7.     display: inline-block;
  8.     margin-left: 10px;
  9.     vertical-align: middle;
  10.     color: #666;
  11.     font-size: 14px;
  12. }

自定义样式

可以通过 displayRender 来定制单选时展示的结果，可以通过 listStyle，listClassName 来定制组件宽高。

CascaderSelect 级联选择 - 图7

查看源码在线预览

  1. import { CascaderSelect, Icon } from '@alifd/next';
  3. const dataSource = [{
  4.     value: '2973',
  5.     label: '陕西',
  6.     children: [{
  7.         value: '2974',
  8.         label: '西安',
  9.         children: [
  10.             { value: '2975', label: '西安市' },
  11.             { value: '2976', label: '高陵县' }
  12.         ]
  13.     }, {
  14.         value: '2980',
  15.         label: '铜川',
  16.         children: [
  17.             { value: '2981', label: '铜川市' },
  18.             { value: '2982', label: '宜君县' }
  19.         ]
  20.     }]
  21. }, {
  22.     value: '3371',
  23.     label: '新疆',
  24.     children: [{
  25.         value: '3430',
  26.         label: '巴音郭楞蒙古自治州',
  27.         children: [
  28.             { value: '3431', label: '库尔勒市' },
  29.             { value: '3432', label: '和静县' }
  30.         ]
  31.     }]
  32. }];
  34. const itemRender = item => {
  35.     return (
  36.         <span>
  37.             <Icon type="account" size="xs" /> {item.label}
  38.         </span>
  39.     );
  40. };
  42. ReactDOM.render(<CascaderSelect style={{ width: '452px'}} listStyle={{ width: '150px', height: '160px' }} displayRender={labels => labels[labels.length - 1]} defaultValue="3431" dataSource={dataSource} itemRender={itemRender} />, mountNode);

异步加载数据

展示动态获取数据的用法。

CascaderSelect 级联选择 - 图8

查看源码在线预览

  1. import { CascaderSelect } from '@alifd/next';
  3. const dataSource = [{
  4.     value: '2973',
  5.     label: '陕西'
  6. }];
  8. class Demo extends React.Component {
  9.     constructor(props) {
  10.         super(props);
  12.         this.state = {
  13.             dataSource
  14.         };
  16.         this.onLoadData = this.onLoadData.bind(this);
  17.     }
  19.     onLoadData(data) {
  20.         console.log(data);
  22.         return new Promise(resolve => {
  23.             setTimeout(() => {
  24.                 this.setState({
  25.                     dataSource: [{
  26.                         value: '2973',
  27.                         label: '陕西',
  28.                         children: [{
  29.                             value: '2974',
  30.                             label: '西安',
  31.                             children: [
  32.                                 { value: '2975', label: '西安市', isLeaf: true },
  33.                                 { value: '2976', label: '高陵县', isLeaf: true }
  34.                             ]
  35.                         }, {
  36.                             value: '2980',
  37.                             label: '铜川',
  38.                             children: [
  39.                                 { value: '2981', label: '铜川市', isLeaf: true },
  40.                                 { value: '2982', label: '宜君县', isLeaf: true }
  41.                             ]
  42.                         }]
  43.                     }]
  44.                 }, resolve);
  45.             }, 500);
  46.         });
  47.     }
  49.     render() {
  50.         return <CascaderSelect style={{ width: '302px' }} dataSource={this.state.dataSource} loadData={this.onLoadData} />;
  51.     }
  52. }
  54. ReactDOM.render(<Demo />, mountNode);

渲染 DataSource 中不存在的 value

CascaderSelect 级联选择 - 图9

查看源码在线预览

  1. import { CascaderSelect } from '@alifd/next';
  3. class Demo extends React.Component {
  4.     constructor(props) {
  5.         super(props);
  7.         this.state = {
  8.             data: []
  9.         };
  11.         this.handleChange = this.handleChange.bind(this);
  12.     }
  14.     componentDidMount() {
  15.         fetch('https://os.alipayobjects.com/rmsportal/ODDwqcDFTLAguOvWEolX.json')
  16.             .then(response => response.json())
  17.             .then(data => {
  18.                 data[1].disabled = true;
  19.                 this.setState({ data });
  20.             })
  21.             .catch(e => console.log(e));
  22.     }
  24.     handleChange(value, data, extra) {
  25.         console.log(value, data, extra);
  26.     }
  28.     valueRender = (item) => {
  29.         if (item.label) {
  30.             return item.label; // 正常的item
  31.         }
  33.         // value在 dataSouce里不存在时渲染。
  34.         return item.value === '432988' ? '不存在的' : item.value;
  35.     };
  37.     render() {
  38.         return <CascaderSelect valueRender={this.valueRender} defaultValue="432988" style={{ width: '302px' }} dataSource={this.state.data} onChange={this.handleChange} />;
  39.     }
  40. }
  41. ReactDOM.render(<Demo />, mountNode);

无障碍

当聚焦在组件上时，通过aria-labelledby对组件进行描述。关于键盘操作请参考ARIA and KeyBoard。

CascaderSelect 级联选择 - 图10

查看源码在线预览

  1. import { CascaderSelect } from '@alifd/next';
  3. const data = [{
  4.     value: '0100',
  5.     label: '金庸',
  6.     children: [
  7.         { value: '0101', label: '飞狐外传' },
  8.         { value: '0102', label: '雪山飞狐' },
  9.         { value: '0103', label: '连城诀' },
  10.         { value: '0104', label: '天龙八部' },
  11.         { value: '0105', label: '射雕英雄传' },
  12.         { value: '0106', label: '白马啸西风' },
  13.         { value: '0107', label: '鹿鼎记' },
  14.         { value: '0108', label: '笑傲江湖' },
  15.         { value: '0109', label: '书剑恩仇录' },
  16.         { value: '0110', label: '神雕侠侣' },
  17.         { value: '0111', label: '侠客行' },
  18.         { value: '0112', label: '倚天屠龙记' },
  19.         { value: '0113', label: '碧血剑' },
  20.         { value: '0114', label: '鸳鸯刀' }
  21.     ]
  22. }, {
  23.     value: '0200',
  24.     label: '古龙',
  25.     children: [
  26.         { value: '0201', label: '小李飞刀' },
  27.         { value: '0202', label: '绝代双骄' },
  28.         { value: '0203', label: '大旗英雄传' },
  29.         { value: '0204', label: '英雄无泪' },
  30.         { value: '0205', label: '边城浪子' },
  31.         { value: '0206', label: '楚留香传奇' },
  32.     ],
  33. }, {
  34.     children: [
  35.         { value: '0301', label: '白发魔女传' },
  36.         { value: '0302', label: '七剑下天山' },
  37.         { value: '0303', label: '云海玉弓缘' }
  38.     ],
  39.     value: '0300',
  40.     label: '梁羽生'
  41. }];
  43. class Demo extends React.Component {
  44.     constructor(props) {
  45.         super(props);
  46.         this.state = {
  47.             label: '',
  48.             data: []
  49.         };
  50.         this.handleChange = this.handleChange.bind(this);
  51.     }
  52.     componentDidMount() {
  53.         this.setState({ data });
  54.     }
  55.     handleChange(value, data, extra) {
  56.         console.log(value, data, extra);
  58.         this.setState({
  59.             label: extra.selectedPath.map(d => d.label).join(' / '),       
  60.         });
  61.     }
  62.     render() {
  63.         return (
  64.             <div>
  65.                 <div id="a11y-cascader-select" >CascaderSelect: </div>
  66.                 <CascaderSelect  dataSource={this.state.data} onChange={this.handleChange} listStyle={{ width: '200px', height: '256px' }} aria-labelledby="a11y-cascader-select"/>
  67.             </div>
  68.         );
  69.     }
  70. }
  71. ReactDOM.render(<Demo />, mountNode);
  1. .next-menu-item:focus {
  2.     background-color: #F2F3F7;
  3. }

相关区块

CascaderSelect 级联选择 - 图11

暂无相关区块