feat(module:cascader): add nzOpen to control visibility (#9339)

Author: WwwHhhYran

components/cascader/cascader.component.ts

@@ -347,6 +347,7 @@ export class NzCascaderComponent
   @ViewChild(CdkConnectedOverlay, { static: false }) overlay!: CdkConnectedOverlay;
   @ViewChildren(NzCascaderOptionComponent) cascaderItems!: QueryList<NzCascaderOptionComponent>;
 
+  @Input() nzOpen: boolean = false;
   @Input() nzOptions: NzCascaderOption[] | null = [];
   @Input() nzOptionRender: TemplateRef<{ $implicit: NzCascaderOption; index: number }> | null = null;
   @Input({ transform: booleanAttribute }) nzShowInput = true;
@@ -582,7 +583,10 @@ export class NzCascaderComponent
   }
 
   ngOnChanges(changes: SimpleChanges): void {
-    const { nzStatus, nzSize, nzPlacement, nzOptions } = changes;
+    const { nzOpen, nzStatus, nzSize, nzPlacement, nzOptions } = changes;
+    if (nzOpen) {
+      this.setMenuVisible(this.nzOpen);
+    }
     if (nzOptions) {
       this.updateOptions();
     }

components/cascader/cascader.spec.ts

@@ -1754,6 +1754,23 @@ describe('cascader', () => {
       fixture.detectChanges();
       expect(testComponent.values).toEqual(['zhejiang', 'hangzhou', 'xihu']);
     }));
+
+    it('should nzOpen works', fakeAsync(() => {
+      fixture.detectChanges();
+      expect(testComponent.cascader.menuVisible).toBe(false);
+      expect(testComponent.nzDisabled).toBe(false);
+      testComponent.nzOpen = true;
+      tick(200);
+      fixture.detectChanges();
+      expect(testComponent.cascader.menuVisible).toBe(true);
+      expect(testComponent.onVisibleChange).toHaveBeenCalledTimes(1);
+
+      testComponent.nzOpen = false;
+      tick(200);
+      fixture.detectChanges();
+      expect(testComponent.cascader.menuVisible).toBe(false);
+      expect(testComponent.onVisibleChange).toHaveBeenCalledTimes(2);
+    }));
   });
 
   describe('multiple', () => {
@@ -2443,6 +2460,7 @@ const options5: NzSafeAny[] = [];
   template: `
     <nz-cascader
       [(ngModel)]="values"
+      [nzOpen]="nzOpen"
       [nzOptions]="nzOptions"
       [nzAllowClear]="nzAllowClear"
       [nzAutoFocus]="nzAutoFocus"
@@ -2489,6 +2507,7 @@ export class NzDemoCascaderDefaultComponent {
   nzOptions: NzSafeAny[] | null = options1;
   values: string[] | number[] | null = null;
 
+  nzOpen = false;
   nzAllowClear = true;
   nzAutoFocus = false;
   nzMenuClassName = 'menu-classA menu-classB';

components/cascader/demo/open.md

@@ -0,0 +1,14 @@
+---
+order: 21
+title:
+  zh-CN: 控制浮层显隐
+  en-US: Controlled Opening
+---
+
+## zh-CN
+
+使用 `nzOpen` 控制菜单浮层显隐。
+
+## en-US
+
+Use `nzOpen` to control whether the menu overlay is displayed.

components/cascader/demo/open.ts

@@ -0,0 +1,64 @@
+import { Component } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+
+import { NzCascaderModule, NzCascaderOption } from 'ng-zorro-antd/cascader';
+import { NzFlexModule } from 'ng-zorro-antd/flex';
+import { NzSwitchModule } from 'ng-zorro-antd/switch';
+
+const options: NzCascaderOption[] = [
+  {
+    value: 'zhejiang',
+    label: 'Zhejiang',
+    children: [
+      {
+        value: 'hangzhou',
+        label: 'Hangzhou',
+        children: [
+          {
+            value: 'xihu',
+            label: 'West Lake',
+            isLeaf: true
+          }
+        ]
+      },
+      {
+        value: 'ningbo',
+        label: 'Ningbo',
+        isLeaf: true
+      }
+    ]
+  },
+  {
+    value: 'jiangsu',
+    label: 'Jiangsu',
+    children: [
+      {
+        value: 'nanjing',
+        label: 'Nanjing',
+        children: [
+          {
+            value: 'zhonghuamen',
+            label: 'Zhong Hua Men',
+            isLeaf: true
+          }
+        ]
+      }
+    ]
+  }
+];
+
+@Component({
+  selector: 'nz-demo-cascader-open',
+  imports: [FormsModule, NzCascaderModule, NzFlexModule, NzSwitchModule],
+  template: `
+    <div nz-flex nzVertical nzGap="small">
+      <nz-switch nzSize="small" [(ngModel)]="open" nzCheckedChildren="open" nzUnCheckedChildren="close"></nz-switch>
+      <nz-cascader [nzOptions]="nzOptions" [ngModel]="values" [nzOpen]="open"></nz-cascader>
+    </div>
+  `
+})
+export class NzDemoCascaderOpenComponent {
+  nzOptions = options;
+  values = ['zhejiang', 'hangzhou', 'xihu'];
+  open = false;
+}

components/cascader/demo/variant.md

@@ -1,5 +1,5 @@
 ---
-order: 21
+order: 20
 title:
   zh-CN: 形态变体
   en-US: Variants

components/cascader/doc/index.en-US.md

@@ -43,6 +43,7 @@ description: Cascade selection box.
 | `[nzNotFoundContent]` | specify content to show when no result matches                                                                                         | `string \| TemplateRef<void>`                                         | -                 |
 | `[nzOptionRender]`    | render template of cascader options                                                                                                    | `TemplateRef<{ $implicit: NzCascaderOption, index: number }>`         |                   |
 | `[nzOptions]`         | data options of cascade                                                                                                                | `object[]`                                                            | -                 |
+| `[nzOpen]`            | Set visible of cascader popup                                                                                                          | `boolean`                                                             | `false`           |
 | `[nzPlaceHolder]`     | input placeholder                                                                                                                      | `string`                                                              | `'Please select'` |
 | `[nzPlacement]`       | popup placement                                                                                                                        | `'bottomLeft' \| 'bottomRight' \| 'topLeft' \| 'topRight'`            | `'bottomLeft'`    |
 | `[nzShowArrow]`       | whether show arrow                                                                                                                     | `boolean`                                                             | `true`            |

components/cascader/doc/index.zh-CN.md

@@ -44,6 +44,7 @@ description: 级联选择框。
 | `[nzNotFoundContent]` | 当下拉列表为空时显示的内容                                                                 | `string \| TemplateRef<void>`                                         | -              |
 | `[nzOptionRender]`    | 选项的渲染模板                                                                             | `TemplateRef<{ $implicit: NzCascaderOption, index: number }>`         |                |
 | `[nzOptions]`         | 可选项数据源                                                                               | `object[]`                                                            | -              |
+| `[nzOpen]`            | 控制浮层显隐                                                                               | `boolean`                                                             | `false`        |
 | `[nzPlaceHolder]`     | 输入框占位文本                                                                             | `string`                                                              | `'请选择'`     |
 | `[nzPlacement]`       | 浮层弹出位置                                                                               | `'bottomLeft' \| 'bottomRight' \| 'topLeft' \| 'topRight'`            | `'bottomLeft'` |
 | `[nzShowArrow]`       | 是否显示箭头                                                                               | `boolean`                                                             | `true`         |