Cascader级联选择

级联选择框。

何时使用#

  • 需要从一组相关联的数据集合进行选择,例如省市区,公司层级,事物分类等。
  • 从一个较大的数据集合中进行选择时,用多级分类进行分隔,方便选择。
  • 比起 Select 组件,可以在同一个浮层中完成选择,有较好的体验。
import { NzCascaderModule } from 'ng-zorro-antd/cascader';

代码演示

请选择
  Change Options

省市区级联。

expand codeexpand code
加载中
Unselect

切换按钮和结果分开。

expand codeexpand code
加载中
请选择

通过指定 options 里的 disabled 字段。

expand codeexpand code
加载中
请选择
请选择
请选择

不同大小的级联选择器。

expand codeexpand code
加载中
请选择

通过表单的重置功能清空已选择的值。

expand codeexpand code
加载中
请选择

通过函数来判断选项是否可以选择。

expand codeexpand code
加载中
Zhejiang / Hangzhou / West Lake

默认值通过数组的方式指定,但nzOptions没有赋值,通过nzLoadData函数延迟加载。

expand codeexpand code
加载中
请选择

自定义字段名。

expand codeexpand code
加载中
请选择
请选择

使用 nzStatus 为 Cascader 添加状态,可选 error 或者 warning

expand codeexpand code
加载中
Zhejiang / Hangzhou / West Lake

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

expand codeexpand code
加载中
请选择

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

expand codeexpand code
加载中
请选择

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

expand codeexpand code
加载中
请选择

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

expand codeexpand code
加载中
请选择

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

expand codeexpand code
加载中

在模态窗口中使用级联控件。

expand codeexpand code
加载中
请选择

鼠标移入触发显示菜单,移出隐藏菜单。

expand codeexpand code
加载中
Zhejiang / Hangzhou / West Lake

默认值通过数组的方式指定,但nzOptions通过异步加载。

expand codeexpand code
加载中
请选择

自定义选项的模板。

expand codeexpand code
加载中

API#

<nz-cascader [nzOptions]="options" [(ngModel)]="values"></nz-cascader>

nz-cascader#

参数说明类型默认值支持全局配置
[ngModel]指定选中项any[]-
[nzAllowClear]是否支持清除booleantrue
[nzAutoFocus]是否自动聚焦,当存在输入框时booleanfalse
[nzBackdrop]浮层是否应带有背景板booleanfalse
[nzChangeOn]点击父级菜单选项时,可通过该函数判断是否允许值的变化(option: any, index: number) => boolean-
[nzChangeOnSelect]当此项为 true 时,点选每级菜单选项值都会发生变化,具体见上面的演示booleanfalse
[nzColumnClassName]自定义浮层列类名string-
[nzDisabled]禁用booleanfalse
[nzExpandIcon]自定义次级菜单展开图标string|TemplateRef<void>-
[nzExpandTrigger]次级菜单的展开方式,可选 'click' 和 'hover''click'|'hover''click'
[nzLabelProperty]选项的显示值的属性名string'label'
[nzLabelRender]选择后展示的渲染模板TemplateRef<any>-
[nzLoadData]用于动态加载选项。如果提供了ngModel初始值,且未提供nzOptions值,则会立即触发动态加载。(option: any, index?: index) => PromiseLike<any> | Observable<any>-
[nzMenuClassName]自定义浮层类名string-
[nzMenuStyle]自定义浮层样式object-
[nzNotFoundContent]当下拉列表为空时显示的内容string|TemplateRef<void>-
[nzOptionRender]选项的渲染模板TemplateRef<{ $implicit: NzCascaderOption, index: number }>
[nzOptions]可选项数据源object[]-
[nzPlaceHolder]输入框占位文本string'请选择'
[nzShowArrow]是否显示箭头booleantrue
[nzShowInput]显示输入框booleantrue
[nzShowSearch]是否支持搜索,默认情况下对 label 进行全匹配搜索,不能和 [nzLoadData] 同时使用boolean|NzShowSearchOptionsfalse
[nzSize]输入框大小,可选 largedefaultsmall'large'|'small'|'default''default'
[nzStatus]设置校验状态'error' | 'warning'-
[nzSuffixIcon]自定义的选择框后缀图标string|TemplateRef<void>-
[nzValueProperty]选项的实际值的属性名string'value'
(ngModelChange)值发生变化时触发EventEmitter<any[]>-
(nzClear)清除值时触发EventEmitter<void>-
(nzVisibleChange)菜单浮层的显示/隐藏EventEmitter<boolean>-
(nzSelectionChange)值发生变化时触发EventEmitter<NzCascaderOption[]>-

nzShowSearch 为对象时需遵守 NzShowSearchOptions 接口:

参数说明类型默认值
filter可选,选择是否保留选项的过滤函数,每级菜单的选项都会被匹配(inputValue: string, path: NzCascaderOption[]): boolean-
sorter可选,按照到每个最终选项的路径进行排序,默认按照原始数据的顺序(a: NzCascaderOption[], b: NzCascaderOption[], inputValue: string): number-

默认的 filter 如下所示:

const defaultFilter: NzCascaderFilter = (i, p) => {
  return p.some(o => {
    const label = o.label;
    return !!label && label.indexOf(i) !== -1;
  });
};

如果你想要在搜索时忽略大小写,就可以编写一个这样的 filter 函数:

const filter: NzCascaderFilter = (i, p) => {
  return p.some(o => {
    const label = o.label;
    return !!label && label.toLowerCase().indexOf(i.toLowerCase()) !== -1;
  });
};

方法#

名称描述
blur()移除焦点
focus()获取焦点
closeMenu()隐藏菜单

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

FAQ#

Q: 为什么使用 nzLoadData 时报了一个错误 this === undefined ?#

对传递给 Cascader 组件的 nzLoadData 参数会成为 NzCasacderComponent 对象的一个属性,调用这个函数时,函数中的 this 没有指向任何对象。因此,正确的做法是传递剪头函数,或者使用 Function.bindnzLoadData 参数和你的对象绑定。这里是一个比较有代表性的例子。