Cascader级联选择

级联选择框。

何时使用

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

代码演示

Cascader级联选择 - 图1

基本

省市区级联。

  1. // tslint:disable:no-any
  2. import { Component, OnInit } from '@angular/core';
  4. const options = [
  5.   {
  6.     value: 'zhejiang',
  7.     label: 'Zhejiang',
  8.     children: [
  9.       {
  10.         value: 'hangzhou',
  11.         label: 'Hangzhou',
  12.         children: [
  13.           {
  14.             value: 'xihu',
  15.             label: 'West Lake',
  16.             isLeaf: true
  17.           }
  18.         ]
  19.       },
  20.       {
  21.         value: 'ningbo',
  22.         label: 'Ningbo',
  23.         isLeaf: true
  24.       }
  25.     ]
  26.   },
  27.   {
  28.     value: 'jiangsu',
  29.     label: 'Jiangsu',
  30.     children: [
  31.       {
  32.         value: 'nanjing',
  33.         label: 'Nanjing',
  34.         children: [
  35.           {
  36.             value: 'zhonghuamen',
  37.             label: 'Zhong Hua Men',
  38.             isLeaf: true
  39.           }
  40.         ]
  41.       }
  42.     ]
  43.   }
  44. ];
  46. const otherOptions = [
  47.   {
  48.     value: 'fujian',
  49.     label: 'Fujian',
  50.     children: [
  51.       {
  52.         value: 'xiamen',
  53.         label: 'Xiamen',
  54.         children: [
  55.           {
  56.             value: 'Kulangsu',
  57.             label: 'Kulangsu',
  58.             isLeaf: true
  59.           }
  60.         ]
  61.       }
  62.     ]
  63.   },
  64.   {
  65.     value: 'guangxi',
  66.     label: 'Guangxi',
  67.     children: [
  68.       {
  69.         value: 'guilin',
  70.         label: 'Guilin',
  71.         children: [
  72.           {
  73.             value: 'Lijiang',
  74.             label: 'Li Jiang River',
  75.             isLeaf: true
  76.           }
  77.         ]
  78.       }
  79.     ]
  80.   }
  81. ];
  83. @Component({
  84.   selector: 'nz-demo-cascader-basic',
  85.   template: `
  86.     <nz-cascader [nzOptions]="nzOptions" [(ngModel)]="values" (ngModelChange)="onChanges($event)"></nz-cascader>
  87.     &nbsp;
  88.     <a href="javascript:;" (click)="changeNzOptions()" class="change-options">
  89.       Change Options
  90.     </a>
  91.   `,
  92.   styles: [
  93.     `
  94.       .change-options {
  95.         display: inline-block;
  96.         font-size: 12px;
  97.         margin-top: 8px;
  98.       }
  99.     `
  100.   ]
  101. })
  102. export class NzDemoCascaderBasicComponent implements OnInit {
  103.   nzOptions: any[] | null = null;
  104.   values: any[] | null = null;
  106.   ngOnInit(): void {
  107.     setTimeout(() => {
  108.       this.nzOptions = options;
  109.     }, 100);
  110.   }
  112.   changeNzOptions(): void {
  113.     if (this.nzOptions === options) {
  114.       this.nzOptions = otherOptions;
  115.     } else {
  116.       this.nzOptions = options;
  117.     }
  118.   }
  120.   onChanges(values: any): void {
  121.     console.log(values, this.values);
  122.   }
  123. }

Cascader级联选择 - 图2

可以自定义显示

切换按钮和结果分开。

  1. import { Component } from '@angular/core';
  2. import { NzCascaderOption } from 'ng-zorro-antd/cascader';
  4. const options = [
  5.   {
  6.     value: 'zhejiang',
  7.     label: 'Zhejiang',
  8.     children: [
  9.       {
  10.         value: 'hangzhou',
  11.         label: 'Hangzhou',
  12.         children: [
  13.           {
  14.             value: 'xihu',
  15.             label: 'West Lake',
  16.             isLeaf: true
  17.           }
  18.         ]
  19.       },
  20.       {
  21.         value: 'ningbo',
  22.         label: 'Ningbo',
  23.         isLeaf: true
  24.       }
  25.     ]
  26.   },
  27.   {
  28.     value: 'jiangsu',
  29.     label: 'Jiangsu',
  30.     children: [
  31.       {
  32.         value: 'nanjing',
  33.         label: 'Nanjing',
  34.         children: [
  35.           {
  36.             value: 'zhonghuamen',
  37.             label: 'Zhong Hua Men',
  38.             isLeaf: true
  39.           }
  40.         ]
  41.       }
  42.     ]
  43.   }
  44. ];
  46. @Component({
  47.   selector: 'nz-demo-cascader-trigger',
  48.   template: `
  49.     {{ text }}
  50.     <nz-cascader
  51.       [nzShowInput]="false"
  52.       [nzOptions]="nzOptions"
  53.       [(ngModel)]="values"
  54.       (ngModelChange)="onChanges($event)"
  55.       (nzSelectionChange)="onSelectionChange($event)"
  56.     >
  57.       <a href="javascript: void(0)">Change city</a>
  58.     </nz-cascader>
  59.   `
  60. })
  61. export class NzDemoCascaderTriggerComponent {
  62.   nzOptions: NzCascaderOption[] = options;
  63.   values: string[] | null = null;
  64.   text = 'Unselect';
  66.   onChanges(values: string[]): void {
  67.     console.log(values, this.values);
  68.   }
  70.   onSelectionChange(selectedOptions: NzCascaderOption[]): void {
  71.     this.text = selectedOptions.map(o => o.label).join(', ');
  72.   }
  73. }

Cascader级联选择 - 图3

禁用选项

通过指定 options 里的 disabled 字段。

  1. import { Component } from '@angular/core';
  2. import { NzCascaderOption } from 'ng-zorro-antd/cascader';
  4. const options = [
  5.   {
  6.     value: 'zhejiang',
  7.     label: 'Zhejiang',
  8.     children: [
  9.       {
  10.         value: 'hangzhou',
  11.         label: 'Hangzhou',
  12.         children: [
  13.           {
  14.             value: 'xihu',
  15.             label: 'West Lake',
  16.             isLeaf: true
  17.           }
  18.         ]
  19.       },
  20.       {
  21.         value: 'ningbo',
  22.         label: 'Ningbo',
  23.         isLeaf: true
  24.       }
  25.     ]
  26.   },
  27.   {
  28.     value: 'jiangsu',
  29.     label: 'Jiangsu',
  30.     disabled: true,
  31.     children: [
  32.       {
  33.         value: 'nanjing',
  34.         label: 'Nanjing',
  35.         children: [
  36.           {
  37.             value: 'zhonghuamen',
  38.             label: 'Zhong Hua Men',
  39.             isLeaf: true
  40.           }
  41.         ]
  42.       }
  43.     ]
  44.   }
  45. ];
  47. @Component({
  48.   selector: 'nz-demo-cascader-disabled',
  49.   template: `
  50.     <nz-cascader [nzOptions]="nzOptions" [(ngModel)]="values" (ngModelChange)="onChanges($event)"> </nz-cascader>
  51.   `
  52. })
  53. export class NzDemoCascaderDisabledComponent {
  54.   nzOptions: NzCascaderOption[] = options;
  55.   values: string[] | null = null;
  57.   onChanges(values: string[]): void {
  58.     console.log(values, this.values);
  59.   }
  60. }

Cascader级联选择 - 图4

大小

不同大小的级联选择器。

  1. import { Component } from '@angular/core';
  2. import { NzCascaderOption } from 'ng-zorro-antd/cascader';
  4. const options = [
  5.   {
  6.     value: 'zhejiang',
  7.     label: 'Zhejiang',
  8.     children: [
  9.       {
  10.         value: 'hangzhou',
  11.         label: 'Hangzhou',
  12.         children: [
  13.           {
  14.             value: 'xihu',
  15.             label: 'West Lake',
  16.             isLeaf: true
  17.           }
  18.         ]
  19.       },
  20.       {
  21.         value: 'ningbo',
  22.         label: 'Ningbo',
  23.         isLeaf: true
  24.       }
  25.     ]
  26.   },
  27.   {
  28.     value: 'jiangsu',
  29.     label: 'Jiangsu',
  30.     children: [
  31.       {
  32.         value: 'nanjing',
  33.         label: 'Nanjing',
  34.         children: [
  35.           {
  36.             value: 'zhonghuamen',
  37.             label: 'Zhong Hua Men',
  38.             isLeaf: true
  39.           }
  40.         ]
  41.       }
  42.     ]
  43.   }
  44. ];
  46. @Component({
  47.   selector: 'nz-demo-cascader-size',
  48.   template: `
  49.     <nz-cascader [nzSize]="'large'" [nzOptions]="nzOptions" [(ngModel)]="value1" (ngModelChange)="onChanges($event)"> </nz-cascader>
  50.     <nz-cascader [nzOptions]="nzOptions" [(ngModel)]="value2" (ngModelChange)="onChanges($event)"> </nz-cascader>
  51.     <nz-cascader [nzSize]="'small'" [nzOptions]="nzOptions" [(ngModel)]="value3" (ngModelChange)="onChanges($event)"> </nz-cascader>
  52.   `,
  53.   styles: [
  54.     `
  55.       .ant-cascader-picker {
  56.         width: 300px;
  57.         margin-bottom: 8px;
  58.       }
  59.     `
  60.   ]
  61. })
  62. export class NzDemoCascaderSizeComponent {
  63.   nzOptions: NzCascaderOption[] = options;
  64.   value1: string[] | null = null;
  65.   value2: string[] | null = null;
  66.   value3: string[] | null = null;
  68.   onChanges(values: string[]): void {
  69.     console.log(values);
  70.   }
  71. }

Cascader级联选择 - 图5

响应表单

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

  1. import { Component, OnDestroy } from '@angular/core';
  2. import { FormBuilder, FormControl, FormGroup, Validators } from '@angular/forms';
  3. import { NzCascaderOption } from 'ng-zorro-antd/cascader';
  4. import { Subscription } from 'rxjs';
  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.             isLeaf: true
  19.           }
  20.         ]
  21.       },
  22.       {
  23.         value: 'ningbo',
  24.         label: 'Ningbo',
  25.         isLeaf: true
  26.       }
  27.     ]
  28.   },
  29.   {
  30.     value: 'jiangsu',
  31.     label: 'Jiangsu',
  32.     children: [
  33.       {
  34.         value: 'nanjing',
  35.         label: 'Nanjing',
  36.         children: [
  37.           {
  38.             value: 'zhonghuamen',
  39.             label: 'Zhong Hua Men',
  40.             isLeaf: true
  41.           }
  42.         ]
  43.       }
  44.     ]
  45.   }
  46. ];
  48. @Component({
  49.   selector: 'nz-demo-cascader-reactive-form',
  50.   template: `
  51.     <form [formGroup]="form" novalidate>
  52.       <nz-cascader [nzOptions]="nzOptions" [formControlName]="'name'"> </nz-cascader>
  53.     </form>
  54.     <br />
  55.     <button nz-button (click)="reset()">Reset</button>
  56.     <button nz-button (click)="submit()">Submit</button>
  57.   `,
  58.   styles: [
  59.     `
  60.       button {
  61.         margin-right: 8px;
  62.       }
  63.     `
  64.   ]
  65. })
  66. export class NzDemoCascaderReactiveFormComponent implements OnDestroy {
  67.   form!: FormGroup;
  68.   nzOptions: NzCascaderOption[] = options;
  69.   changeSubscription: Subscription;
  70.   constructor(private fb: FormBuilder) {
  71.     this.createForm();
  72.     const control = this.form.get('name') as FormControl;
  73.     this.changeSubscription = control.valueChanges.subscribe(data => {
  74.       this.onChanges(data);
  75.     });
  76.   }
  78.   private createForm(): void {
  79.     this.form = this.fb.group({
  80.       name: [null, Validators.required]
  81.     });
  82.   }
  84.   reset(): void {
  85.     this.form.reset();
  86.     console.log(this.form.value);
  87.   }
  89.   submit(): void {
  90.     console.log(this.form.value);
  91.   }
  93.   onChanges(values: string[]): void {
  94.     console.log(values);
  95.   }
  97.   ngOnDestroy(): void {
  98.     this.changeSubscription.unsubscribe();
  99.   }
  100. }

Cascader级联选择 - 图6

指定选择

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

  1. import { Component } from '@angular/core';
  2. import { NzCascaderOption } from 'ng-zorro-antd/cascader';
  4. const options = [
  5.   {
  6.     value: 'zhejiang',
  7.     label: 'Zhejiang',
  8.     children: [
  9.       {
  10.         value: 'hangzhou',
  11.         label: 'Hangzhou',
  12.         children: [
  13.           {
  14.             value: 'xihu',
  15.             label: 'West Lake',
  16.             isLeaf: true
  17.           }
  18.         ]
  19.       },
  20.       {
  21.         value: 'ningbo',
  22.         label: 'Ningbo',
  23.         children: [
  24.           {
  25.             value: 'dongqianlake',
  26.             label: 'Dongqian Lake',
  27.             isLeaf: true
  28.           }
  29.         ]
  30.       }
  31.     ]
  32.   },
  33.   {
  34.     value: 'jiangsu',
  35.     label: 'Jiangsu',
  36.     children: [
  37.       {
  38.         value: 'nanjing',
  39.         label: 'Nanjing',
  40.         children: [
  41.           {
  42.             value: 'zhonghuamen',
  43.             label: 'Zhong Hua Men',
  44.             isLeaf: true
  45.           }
  46.         ]
  47.       }
  48.     ]
  49.   }
  50. ];
  52. @Component({
  53.   selector: 'nz-demo-cascader-change-on-function',
  54.   template: `
  55.     <nz-cascader [nzChangeOn]="validate" [nzOptions]="nzOptions" [(ngModel)]="values" (ngModelChange)="onChanges($event)"> </nz-cascader>
  56.   `
  57. })
  58. export class NzDemoCascaderChangeOnFunctionComponent {
  59.   nzOptions: NzCascaderOption[] = options;
  60.   values: string[] | null = null;
  62.   onChanges(values: string[]): void {
  63.     console.log(values, this.values);
  64.   }
  66.   validate(option: NzCascaderOption, _index: number): boolean {
  67.     const value = option.value as string;
  68.     return ['hangzhou', 'xihu', 'nanjing', 'zhonghuamen'].indexOf(value) >= 0;
  69.   }
  70. }

Cascader级联选择 - 图7

搜索

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

  1. import { Component, OnInit } from '@angular/core';
  2. import { NzCascaderOption } from 'ng-zorro-antd/cascader';
  4. const options = [
  5.   {
  6.     value: 'zhejiang',
  7.     label: 'Zhejiang',
  8.     children: [
  9.       {
  10.         value: 'hangzhou',
  11.         label: 'Hangzhou',
  12.         children: [
  13.           {
  14.             value: 'xihu',
  15.             label: 'West Lake',
  16.             isLeaf: true
  17.           }
  18.         ]
  19.       },
  20.       {
  21.         value: 'ningbo',
  22.         label: 'Ningbo',
  23.         isLeaf: true,
  24.         disabled: true
  25.       }
  26.     ]
  27.   },
  28.   {
  29.     value: 'jiangsu',
  30.     label: 'Jiangsu',
  31.     children: [
  32.       {
  33.         value: 'nanjing',
  34.         label: 'Nanjing',
  35.         children: [
  36.           {
  37.             value: 'zhonghuamen',
  38.             label: 'Zhong Hua Men',
  39.             isLeaf: true
  40.           }
  41.         ]
  42.       }
  43.     ]
  44.   }
  45. ];
  47. const otherOptions = [
  48.   {
  49.     value: 'fujian',
  50.     label: 'Fujian',
  51.     children: [
  52.       {
  53.         value: 'xiamen',
  54.         label: 'Xiamen',
  55.         children: [
  56.           {
  57.             value: 'Kulangsu',
  58.             label: 'Kulangsu',
  59.             isLeaf: true
  60.           }
  61.         ]
  62.       }
  63.     ]
  64.   },
  65.   {
  66.     value: 'guangxi',
  67.     label: 'Guangxi',
  68.     children: [
  69.       {
  70.         value: 'guilin',
  71.         label: 'Guilin',
  72.         children: [
  73.           {
  74.             value: 'Lijiang',
  75.             label: 'Li Jiang River',
  76.             isLeaf: true
  77.           }
  78.         ]
  79.       }
  80.     ]
  81.   }
  82. ];
  84. @Component({
  85.   selector: 'nz-demo-cascader-search',
  86.   template: `
  87.     <nz-cascader [nzOptions]="nzOptions" [(ngModel)]="values" [nzShowSearch]="true" (ngModelChange)="onChanges($event)"> </nz-cascader>
  88.     &nbsp;
  89.     <a href="javascript:;" (click)="changeNzOptions()" class="change-options">
  90.       Change Options
  91.     </a>
  92.   `,
  93.   styles: [
  94.     `
  95.       .change-options {
  96.         display: inline-block;
  97.         font-size: 12px;
  98.         margin-top: 8px;
  99.       }
  100.     `
  101.   ]
  102. })
  103. export class NzDemoCascaderSearchComponent implements OnInit {
  104.   nzOptions: NzCascaderOption[] | null = null;
  105.   values: string[] | null = null;
  107.   ngOnInit(): void {
  108.     setTimeout(() => {
  109.       this.nzOptions = options;
  110.     }, 100);
  111.   }
  113.   changeNzOptions(): void {
  114.     if (this.nzOptions === options) {
  115.       this.nzOptions = otherOptions;
  116.     } else {
  117.       this.nzOptions = options;
  118.     }
  119.   }
  121.   onChanges(values: string[]): void {
  122.     console.log(values, this.values);
  123.   }
  124. }

Cascader级联选择 - 图8

默认值与延迟加载

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

  1. import { Component } from '@angular/core';
  2. import { NzCascaderOption } from 'ng-zorro-antd/cascader';
  4. const provinces = [
  5.   {
  6.     value: 'zhejiang',
  7.     label: 'Zhejiang'
  8.   },
  9.   {
  10.     value: 'jiangsu',
  11.     label: 'Jiangsu'
  12.   }
  13. ];
  15. const cities: { [key: string]: Array<{ value: string; label: string; isLeaf?: boolean }> } = {
  16.   zhejiang: [
  17.     {
  18.       value: 'hangzhou',
  19.       label: 'Hangzhou'
  20.     },
  21.     {
  22.       value: 'ningbo',
  23.       label: 'Ningbo',
  24.       isLeaf: true
  25.     }
  26.   ],
  27.   jiangsu: [
  28.     {
  29.       value: 'nanjing',
  30.       label: 'Nanjing'
  31.     }
  32.   ]
  33. };
  35. const scenicspots: { [key: string]: Array<{ value: string; label: string; isLeaf?: boolean }> } = {
  36.   hangzhou: [
  37.     {
  38.       value: 'xihu',
  39.       label: 'West Lake',
  40.       isLeaf: true
  41.     }
  42.   ],
  43.   nanjing: [
  44.     {
  45.       value: 'zhonghuamen',
  46.       label: 'Zhong Hua Men',
  47.       isLeaf: true
  48.     }
  49.   ]
  50. };
  52. @Component({
  53.   selector: 'nz-demo-cascader-default-value-and-lazyload',
  54.   template: ` <nz-cascader [(ngModel)]="values" [nzLoadData]="loadData" (ngModelChange)="onChanges($event)"> </nz-cascader> `
  55. })
  56. export class NzDemoCascaderDefaultValueAndLazyloadComponent {
  57.   values: string[] = ['zhejiang', 'hangzhou', 'xihu'];
  59.   onChanges(values: string[]): void {
  60.     console.log(values, this.values);
  61.   }
  63.   /** load data async execute by `nzLoadData` method */
  64.   loadData(node: NzCascaderOption, index: number): PromiseLike<void> {
  65.     return new Promise(resolve => {
  66.       setTimeout(() => {
  67.         if (index < 0) {
  68.           // if index less than 0 it is root node
  69.           node.children = provinces;
  70.         } else if (index === 0) {
  71.           node.children = cities[node.value];
  72.         } else {
  73.           node.children = scenicspots[node.value];
  74.         }
  75.         resolve();
  76.       }, 1000);
  77.     });
  78.   }
  79. }

Cascader级联选择 - 图9

自定义字段名

自定义字段名。

  1. import { Component } from '@angular/core';
  2. import { NzCascaderOption } from 'ng-zorro-antd/cascader';
  4. const options = [
  5.   {
  6.     code: 'zhejiang',
  7.     name: 'Zhejiang',
  8.     children: [
  9.       {
  10.         code: 'hangzhou',
  11.         name: 'Hangzhou',
  12.         children: [
  13.           {
  14.             code: 'xihu',
  15.             name: 'West Lake',
  16.             isLeaf: true
  17.           }
  18.         ]
  19.       },
  20.       {
  21.         code: 'ningbo',
  22.         name: 'Ningbo',
  23.         children: [
  24.           {
  25.             code: 'dongqianlake',
  26.             name: 'Dongqian Lake',
  27.             isLeaf: true
  28.           }
  29.         ]
  30.       }
  31.     ]
  32.   },
  33.   {
  34.     code: 'jiangsu',
  35.     name: 'Jiangsu',
  36.     children: [
  37.       {
  38.         code: 'nanjing',
  39.         name: 'Nanjing',
  40.         children: [
  41.           {
  42.             code: 'zhonghuamen',
  43.             name: 'Zhong Hua Men',
  44.             isLeaf: true
  45.           }
  46.         ]
  47.       }
  48.     ]
  49.   }
  50. ];
  52. @Component({
  53.   selector: 'nz-demo-cascader-custom-field-names',
  54.   template: `
  55.     <nz-cascader
  56.       [nzChangeOn]="validate"
  57.       [nzOptions]="nzOptions"
  58.       [nzLabelProperty]="'name'"
  59.       [nzValueProperty]="'code'"
  60.       [nzShowSearch]="true"
  61.       [(ngModel)]="values"
  62.       (ngModelChange)="onChanges($event)"
  63.     >
  64.     </nz-cascader>
  65.   `
  66. })
  67. export class NzDemoCascaderCustomFieldNamesComponent {
  68.   nzOptions: NzCascaderOption[] = options;
  69.   values: string[] | null = null;
  71.   onChanges(values: string[]): void {
  72.     console.log(values, this.values);
  73.   }
  75.   validate(option: NzCascaderOption, _index: number): boolean {
  76.     const value = option.value as string;
  77.     return ['hangzhou', 'xihu', 'nanjing', 'zhonghuamen'].indexOf(value) >= 0;
  78.   }
  79. }

Cascader级联选择 - 图10

默认值

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

  1. import { Component } from '@angular/core';
  2. import { NzCascaderOption } from 'ng-zorro-antd/cascader';
  4. const options = [
  5.   {
  6.     value: 'zhejiang',
  7.     label: 'Zhejiang',
  8.     children: [
  9.       {
  10.         value: 'hangzhou',
  11.         label: 'Hangzhou',
  12.         children: [
  13.           {
  14.             value: 'xihu',
  15.             label: 'West Lake',
  16.             isLeaf: true
  17.           }
  18.         ]
  19.       },
  20.       {
  21.         value: 'ningbo',
  22.         label: 'Ningbo',
  23.         isLeaf: true
  24.       }
  25.     ]
  26.   },
  27.   {
  28.     value: 'jiangsu',
  29.     label: 'Jiangsu',
  30.     children: [
  31.       {
  32.         value: 'nanjing',
  33.         label: 'Nanjing',
  34.         children: [
  35.           {
  36.             value: 'zhonghuamen',
  37.             label: 'Zhong Hua Men',
  38.             isLeaf: true
  39.           }
  40.         ]
  41.       }
  42.     ]
  43.   }
  44. ];
  46. @Component({
  47.   selector: 'nz-demo-cascader-default-value',
  48.   template: `
  49.     <nz-cascader [nzOptions]="nzOptions" [(ngModel)]="values" (ngModelChange)="onChanges($event)"> </nz-cascader>
  50.   `
  51. })
  52. export class NzDemoCascaderDefaultValueComponent {
  53.   nzOptions: NzCascaderOption[] = options;
  55.   values: string[] = ['zhejiang', 'hangzhou', 'xihu'];
  56.   /* // or like this:
  57.   values: any[] = [{
  58.     value: 'zhejiang',
  59.     label: 'Zhejiang'
  60.   }, {
  61.     value: 'hangzhou',
  62.     label: 'Hangzhou'
  63.   }, {
  64.     value: 'xihu',
  65.     label: 'West Lake'
  66.   }]; */
  68.   onChanges(values: string[]): void {
  69.     console.log(values, this.values);
  70.   }
  71. }

Cascader级联选择 - 图11

移入展开

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

  1. import { Component } from '@angular/core';
  2. import { NzCascaderOption } from 'ng-zorro-antd/cascader';
  4. const options = [
  5.   {
  6.     value: 'zhejiang',
  7.     label: 'Zhejiang',
  8.     children: [
  9.       {
  10.         value: 'hangzhou',
  11.         label: 'Hangzhou',
  12.         children: [
  13.           {
  14.             value: 'xihu',
  15.             label: 'West Lake',
  16.             isLeaf: true
  17.           }
  18.         ]
  19.       },
  20.       {
  21.         value: 'ningbo',
  22.         label: 'Ningbo',
  23.         isLeaf: true
  24.       }
  25.     ]
  26.   },
  27.   {
  28.     value: 'jiangsu',
  29.     label: 'Jiangsu',
  30.     children: [
  31.       {
  32.         value: 'nanjing',
  33.         label: 'Nanjing',
  34.         children: [
  35.           {
  36.             value: 'zhonghuamen',
  37.             label: 'Zhong Hua Men',
  38.             isLeaf: true
  39.           }
  40.         ]
  41.       }
  42.     ]
  43.   }
  44. ];
  46. @Component({
  47.   selector: 'nz-demo-cascader-hover',
  48.   template: `
  49.     <nz-cascader [nzExpandTrigger]="'hover'" [nzOptions]="nzOptions" [(ngModel)]="values" (ngModelChange)="onChanges($event)">
  50.     </nz-cascader>
  51.   `
  52. })
  53. export class NzDemoCascaderHoverComponent {
  54.   nzOptions: NzCascaderOption[] = options;
  55.   values: string[] | null = null;
  57.   onChanges(values: string[]): void {
  58.     console.log(values, this.values);
  59.   }
  60. }

Cascader级联选择 - 图12

选择即改变

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

  1. import { Component } from '@angular/core';
  2. import { NzCascaderOption } from 'ng-zorro-antd/cascader';
  4. const options = [
  5.   {
  6.     value: 'zhejiang',
  7.     label: 'Zhejiang',
  8.     children: [
  9.       {
  10.         value: 'hangzhou',
  11.         label: 'Hangzhou',
  12.         children: [
  13.           {
  14.             value: 'xihu',
  15.             label: 'West Lake',
  16.             isLeaf: true
  17.           }
  18.         ]
  19.       },
  20.       {
  21.         value: 'ningbo',
  22.         label: 'Ningbo',
  23.         isLeaf: true
  24.       }
  25.     ]
  26.   },
  27.   {
  28.     value: 'jiangsu',
  29.     label: 'Jiangsu',
  30.     children: [
  31.       {
  32.         value: 'nanjing',
  33.         label: 'Nanjing',
  34.         children: [
  35.           {
  36.             value: 'zhonghuamen',
  37.             label: 'Zhong Hua Men',
  38.             isLeaf: true
  39.           }
  40.         ]
  41.       }
  42.     ]
  43.   }
  44. ];
  46. @Component({
  47.   selector: 'nz-demo-cascader-change-on-select',
  48.   template: `
  49.     <nz-cascader nzChangeOnSelect [nzOptions]="nzOptions" [(ngModel)]="values" (ngModelChange)="onChanges($event)"> </nz-cascader>
  50.   `
  51. })
  52. export class NzDemoCascaderChangeOnSelectComponent {
  53.   nzOptions: NzCascaderOption[] = options;
  54.   values: string[] | null = null;
  56.   onChanges(values: string[]): void {
  57.     console.log(values, this.values);
  58.   }
  59. }

Cascader级联选择 - 图13

自定义已选项

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

  1. import { Component } from '@angular/core';
  2. import { NzCascaderOption } from 'ng-zorro-antd/cascader';
  4. const options = [
  5.   {
  6.     value: 'zhejiang',
  7.     label: 'Zhejiang',
  8.     children: [
  9.       {
  10.         value: 'hangzhou',
  11.         label: 'Hangzhou',
  12.         children: [
  13.           {
  14.             value: 'xihu',
  15.             label: 'West Lake',
  16.             code: 752100,
  17.             isLeaf: true
  18.           }
  19.         ]
  20.       },
  21.       {
  22.         value: 'ningbo',
  23.         label: 'Ningbo',
  24.         code: '315000',
  25.         isLeaf: true
  26.       }
  27.     ]
  28.   },
  29.   {
  30.     value: 'jiangsu',
  31.     label: 'Jiangsu',
  32.     children: [
  33.       {
  34.         value: 'nanjing',
  35.         label: 'Nanjing',
  36.         children: [
  37.           {
  38.             value: 'zhonghuamen',
  39.             label: 'Zhong Hua Men',
  40.             code: 453400,
  41.             isLeaf: true
  42.           }
  43.         ]
  44.       }
  45.     ]
  46.   }
  47. ];
  49. @Component({
  50.   selector: 'nz-demo-cascader-custom-render',
  51.   template: `
  52.     <nz-cascader [nzLabelRender]="renderTpl" [nzOptions]="nzOptions" [(ngModel)]="values" (ngModelChange)="onChanges($event)">
  53.     </nz-cascader>
  55.     <ng-template #renderTpl let-labels="labels" let-selectedOptions="selectedOptions">
  56.       <ng-container *ngFor="let label of labels; let i = index; let isLast = last">
  57.         <span *ngIf="!isLast">{{ label }} / </span>
  58.         <span *ngIf="isLast">
  59.           {{ label }} (<a href="javascript:;" (click)="handleAreaClick($event, label, selectedOptions[i])">
  60.             {{ selectedOptions[i].code }} </a
  61.           >)
  62.         </span>
  63.       </ng-container>
  64.     </ng-template>
  65.   `
  66. })
  67. export class NzDemoCascaderCustomRenderComponent {
  68.   nzOptions: NzCascaderOption[] = options;
  69.   values: string[] | null = null;
  71.   onChanges(values: string[]): void {
  72.     console.log(values, this.values);
  73.   }
  75.   handleAreaClick(e: Event, label: string, option: NzCascaderOption): void {
  76.     e.preventDefault();
  77.     e.stopPropagation();
  78.     console.log('clicked "', label, '"', option);
  79.   }
  80. }

Cascader级联选择 - 图14

动态加载选项

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

  1. import { Component } from '@angular/core';
  2. import { NzCascaderOption } from 'ng-zorro-antd/cascader';
  4. const provinces = [
  5.   {
  6.     value: 'zhejiang',
  7.     label: 'Zhejiang'
  8.   },
  9.   {
  10.     value: 'jiangsu',
  11.     label: 'Jiangsu'
  12.   }
  13. ];
  15. const cities: { [key: string]: Array<{ value: string; label: string; isLeaf?: boolean }> } = {
  16.   zhejiang: [
  17.     {
  18.       value: 'hangzhou',
  19.       label: 'Hangzhou'
  20.     },
  21.     {
  22.       value: 'ningbo',
  23.       label: 'Ningbo',
  24.       isLeaf: true
  25.     }
  26.   ],
  27.   jiangsu: [
  28.     {
  29.       value: 'nanjing',
  30.       label: 'Nanjing'
  31.     }
  32.   ]
  33. };
  35. const scenicspots: { [key: string]: Array<{ value: string; label: string; isLeaf?: boolean }> } = {
  36.   hangzhou: [
  37.     {
  38.       value: 'xihu',
  39.       label: 'West Lake',
  40.       isLeaf: true
  41.     }
  42.   ],
  43.   nanjing: [
  44.     {
  45.       value: 'zhonghuamen',
  46.       label: 'Zhong Hua Men',
  47.       isLeaf: true
  48.     }
  49.   ]
  50. };
  52. @Component({
  53.   selector: 'nz-demo-cascader-lazy',
  54.   template: `
  55.     <nz-cascader [(ngModel)]="values" [nzLoadData]="loadData" (ngModelChange)="onChanges($event)"> </nz-cascader>
  56.   `
  57. })
  58. export class NzDemoCascaderLazyComponent {
  59.   values: string[] | null = null;
  61.   onChanges(values: string[]): void {
  62.     console.log(values);
  63.   }
  65.   /** load data async execute by `nzLoadData` method */
  66.   loadData(node: NzCascaderOption, index: number): PromiseLike<void> {
  67.     return new Promise(resolve => {
  68.       setTimeout(() => {
  69.         if (index < 0) {
  70.           // if index less than 0 it is root node
  71.           node.children = provinces;
  72.         } else if (index === 0) {
  73.           node.children = cities[node.value];
  74.         } else {
  75.           node.children = scenicspots[node.value];
  76.         }
  77.         resolve();
  78.       }, 1000);
  79.     });
  80.   }
  81. }

Cascader级联选择 - 图15

模态窗口

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

  1. import { Component } from '@angular/core';
  2. import { NzCascaderOption } from 'ng-zorro-antd/cascader';
  4. const options = [
  5.   {
  6.     value: 'zhejiang',
  7.     label: 'Zhejiang',
  8.     children: [
  9.       {
  10.         value: 'hangzhou',
  11.         label: 'Hangzhou',
  12.         children: [
  13.           {
  14.             value: 'xihu',
  15.             label: 'West Lake',
  16.             isLeaf: true
  17.           }
  18.         ]
  19.       },
  20.       {
  21.         value: 'ningbo',
  22.         label: 'Ningbo',
  23.         isLeaf: true
  24.       }
  25.     ]
  26.   },
  27.   {
  28.     value: 'jiangsu',
  29.     label: 'Jiangsu',
  30.     children: [
  31.       {
  32.         value: 'nanjing',
  33.         label: 'Nanjing',
  34.         children: [
  35.           {
  36.             value: 'zhonghuamen',
  37.             label: 'Zhong Hua Men',
  38.             isLeaf: true
  39.           }
  40.         ]
  41.       }
  42.     ]
  43.   }
  44. ];
  46. @Component({
  47.   selector: 'nz-demo-cascader-modal',
  48.   template: `
  49.     <nz-modal [(nzVisible)]="isVisible" nzTitle="Please select" (nzOnCancel)="handleCancel($event)" (nzOnOk)="handleOk($event)">
  50.       <nz-cascader [nzOptions]="nzOptions" [(ngModel)]="values" (ngModelChange)="onChanges($event)"> </nz-cascader>
  51.     </nz-modal>
  53.     <button nz-button (click)="open()">Open Dialog</button>
  54.   `
  55. })
  56. export class NzDemoCascaderModalComponent {
  57.   nzOptions: NzCascaderOption[] = options;
  58.   values: string[] | null = null;
  59.   isVisible = false;
  61.   onChanges(values: string[]): void {
  62.     console.log(values, this.values);
  63.   }
  65.   open(): void {
  66.     this.isVisible = true;
  67.   }
  69.   handleOk($event: MouseEvent): void {
  70.     console.log('Button ok clicked!', this.values, $event);
  71.     this.isVisible = false;
  72.   }
  74.   handleCancel($event: MouseEvent): void {
  75.     console.log('Button cancel clicked!', $event);
  76.     this.isVisible = false;
  77.   }
  78. }

Cascader级联选择 - 图16

鼠标移入触发

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

  1. import { Component } from '@angular/core';
  2. import { NzCascaderOption } from 'ng-zorro-antd/cascader';
  4. const options = [
  5.   {
  6.     value: 'zhejiang',
  7.     label: 'Zhejiang',
  8.     children: [
  9.       {
  10.         value: 'hangzhou',
  11.         label: 'Hangzhou',
  12.         children: [
  13.           {
  14.             value: 'xihu',
  15.             label: 'West Lake',
  16.             isLeaf: true
  17.           }
  18.         ]
  19.       },
  20.       {
  21.         value: 'ningbo',
  22.         label: 'Ningbo',
  23.         isLeaf: true
  24.       }
  25.     ]
  26.   },
  27.   {
  28.     value: 'jiangsu',
  29.     label: 'Jiangsu',
  30.     children: [
  31.       {
  32.         value: 'nanjing',
  33.         label: 'Nanjing',
  34.         children: [
  35.           {
  36.             value: 'zhonghuamen',
  37.             label: 'Zhong Hua Men',
  38.             isLeaf: true
  39.           }
  40.         ]
  41.       }
  42.     ]
  43.   }
  44. ];
  46. @Component({
  47.   selector: 'nz-demo-cascader-trigger-action',
  48.   template: `
  49.     <nz-cascader
  50.       [nzTriggerAction]="'hover'"
  51.       [nzExpandTrigger]="'hover'"
  52.       [nzOptions]="nzOptions"
  53.       [(ngModel)]="values"
  54.       (ngModelChange)="onChanges($event)"
  55.     >
  56.     </nz-cascader>
  57.   `
  58. })
  59. export class NzDemoCascaderTriggerActionComponent {
  60.   nzOptions: NzCascaderOption[] = options;
  61.   values: string[] | null = null;
  63.   onChanges(values: string[]): void {
  64.     console.log(values, this.values);
  65.   }
  66. }

Cascader级联选择 - 图17

默认值与异步列表

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

  1. import { Component, OnInit } from '@angular/core';
  2. import { NzCascaderOption } from 'ng-zorro-antd/cascader';
  4. const options = [
  5.   {
  6.     value: 'zhejiang',
  7.     label: 'Zhejiang',
  8.     children: [
  9.       {
  10.         value: 'hangzhou',
  11.         label: 'Hangzhou',
  12.         children: [
  13.           {
  14.             value: 'xihu',
  15.             label: 'West Lake',
  16.             isLeaf: true
  17.           }
  18.         ]
  19.       },
  20.       {
  21.         value: 'ningbo',
  22.         label: 'Ningbo',
  23.         isLeaf: true
  24.       }
  25.     ]
  26.   },
  27.   {
  28.     value: 'jiangsu',
  29.     label: 'Jiangsu',
  30.     children: [
  31.       {
  32.         value: 'nanjing',
  33.         label: 'Nanjing',
  34.         children: [
  35.           {
  36.             value: 'zhonghuamen',
  37.             label: 'Zhong Hua Men',
  38.             isLeaf: true
  39.           }
  40.         ]
  41.       }
  42.     ]
  43.   }
  44. ];
  46. @Component({
  47.   selector: 'nz-demo-cascader-default-value-and-asyn-options',
  48.   template: `
  49.     <nz-cascader [(ngModel)]="values" [nzOptions]="nzOptions" (ngModelChange)="onChanges($event)"> </nz-cascader>
  50.   `
  51. })
  52. export class NzDemoCascaderDefaultValueAndAsynOptionsComponent implements OnInit {
  53.   nzOptions: NzCascaderOption[] | null = null;
  54.   values: string[] = ['zhejiang', 'hangzhou', 'xihu'];
  56.   onChanges(values: string[]): void {
  57.     console.log(values, this.values);
  58.   }
  60.   ngOnInit(): void {
  61.     setTimeout(() => {
  62.       this.nzOptions = options;
  63.     }, 500);
  64.   }
  65. }

Cascader级联选择 - 图18

自定义选择项

自定义选项的模板。

  1. // tslint:disable:no-any
  2. import { Component } from '@angular/core';
  4. const options = [
  5.   {
  6.     label: 'Ant Design',
  7.     value: 'antd',
  8.     children: [
  9.       {
  10.         label: 'ng-zorro-antd',
  11.         value: 'ng-zorro-antd',
  12.         isLeaf: true
  13.       }
  14.     ]
  15.   },
  16.   {
  17.     label: 'Angular',
  18.     value: 'angular',
  19.     children: [
  20.       {
  21.         label: 'CDK',
  22.         value: 'cdk',
  23.         isLeaf: true
  24.       }
  25.     ]
  26.   }
  27. ];
  29. @Component({
  30.   selector: 'nz-demo-cascader-custom-template',
  31.   template: `
  32.     <nz-cascader [nzOptionRender]="renderTpl" [nzOptions]="nzOptions" [(ngModel)]="values" (ngModelChange)="onChanges($event)">
  33.     </nz-cascader>
  34.     <ng-template #renderTpl let-option let-index="index"> {{ index + 1 }}. {{ option.label }} </ng-template>
  35.   `
  36. })
  37. export class NzDemoCascaderCustomTemplateComponent {
  38.   nzOptions = options;
  39.   values: any[] | null = null;
  41.   onChanges(values: any): void {
  42.     console.log(values, this.values);
  43.   }
  44. }

API

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

nz-cascadercomponent

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

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

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

方法

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

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