feat(module:date-picker): add open and close methods (#5777)

close #3352, close #5771

components/date-picker/date-picker.component.spec.ts

@@ -15,6 +15,7 @@ import { dispatchKeyboardEvent, dispatchMouseEvent, typeInElement } from 'ng-zor
 import { NgStyleInterface } from 'ng-zorro-antd/core/types';
 import { NzI18nModule, NzI18nService, NZ_DATE_LOCALE } from 'ng-zorro-antd/i18n';
 import en_US from '../i18n/languages/en_US';
+import { NzDatePickerComponent } from './date-picker.component';
 import { NzDatePickerModule } from './date-picker.module';
 import { ENTER_EVENT, getPickerAbstract, getPickerInput } from './testing/util';
 import { PREFIX_CLASS } from './util';
@@ -72,6 +73,21 @@ describe('NzDatePickerComponent', () => {
       expect(getPickerContainer()).toBeNull();
     }));
 
+    it('should open and close method work', fakeAsync(() => {
+      fixture.detectChanges();
+      fixtureInstance.datePicker.open();
+      fixture.detectChanges();
+      tick(500);
+      fixture.detectChanges();
+      expect(getPickerContainer()).not.toBeNull();
+
+      fixtureInstance.datePicker.close();
+      fixture.detectChanges();
+      tick(500);
+      fixture.detectChanges();
+      expect(getPickerContainer()).toBeNull();
+    }));
+
     it('should focus on the trigger after a click outside', fakeAsync(() => {
       fixture.detectChanges();
       openPickerByClickTrigger();
@@ -1004,7 +1020,7 @@ class NzTestDatePickerComponent {
   useSuite!: 1 | 2 | 3 | 4;
   @ViewChild('tplDateRender', { static: true }) tplDateRender!: TemplateRef<Date>;
   @ViewChild('tplExtraFooter', { static: true }) tplExtraFooter!: TemplateRef<void>;
-
+  @ViewChild(NzDatePickerComponent, { static: false }) datePicker!: NzDatePickerComponent;
   // --- Suite 1
   nzAllowClear: boolean = false;
   nzAutoFocus: boolean = false;

components/date-picker/date-picker.component.ts

@@ -34,6 +34,7 @@ import { takeUntil } from 'rxjs/operators';
 import { DatePickerService } from './date-picker.service';
 
 import { NzConfigKey, NzConfigService, WithConfig } from 'ng-zorro-antd/core/config';
+import { warnDeprecation } from 'ng-zorro-antd/core/logger';
 import { NzPickerComponent } from './picker.component';
 import { CompatibleDate, DisabledTimeFn, NzDateMode, PresetRanges, SupportTimeOptions } from './standard-types';
 
@@ -132,6 +133,10 @@ export class NzDatePickerComponent implements OnInit, OnChanges, OnDestroy, Cont
   @Input() @InputBoolean() nzAutoFocus: boolean = false;
   @Input() @InputBoolean() nzDisabled: boolean = false;
   @Input() @InputBoolean() nzInputReadOnly: boolean = false;
+  /**
+   * @deprecated use method `open` or `close` instead.
+   * @breaking-change 11.0.0
+   */
   @Input() @InputBoolean() nzOpen?: boolean;
   @Input() nzDisabledDate?: (d: Date) => boolean;
   @Input() nzLocale!: NzDatePickerI18nInterface;
@@ -209,7 +214,7 @@ export class NzDatePickerComponent implements OnInit, OnChanges, OnDestroy, Cont
       }
       this.onTouchedFn();
       // When value emitted, overlay will be closed
-      this.picker.hideOverlay();
+      this.close();
     });
 
     // Default format when it's empty
@@ -242,6 +247,10 @@ export class NzDatePickerComponent implements OnInit, OnChanges, OnDestroy, Cont
       this.extraFooter = valueFunctionProp(this.nzRenderExtraFooter!);
     }
 
+    if (changes.nzOpen) {
+      warnDeprecation(`'nzOpen' in DatePicker is going to be removed in 11.0.0. Please use open() or close() method instead.`);
+    }
+
     if (changes.nzMode) {
       this.setPanelMode();
     }
@@ -266,6 +275,14 @@ export class NzDatePickerComponent implements OnInit, OnChanges, OnDestroy, Cont
     this.nzOnOpenChange.emit(open);
   }
 
+  public open(): void {
+    this.picker.showOverlay();
+  }
+
+  public close(): void {
+    this.picker.hideOverlay();
+  }
+
   // ------------------------------------------------------------------------
   // | Control value accessor implements
   // ------------------------------------------------------------------------

components/date-picker/demo/start-end.md

@@ -9,10 +9,10 @@ title:
 
 当 `RangePicker` 无法满足业务需求时，可以使用两个 `DatePicker` 实现类似的功能。
 > * 通过设置 `nzDisabledDate` 方法，来约束开始和结束日期。
-> * 通过 `nzOpen` `nzOnOpenChange` 来优化交互。
+> * 通过 `open()` 来优化交互。
 
 ## en-US
 
 When `RangePicker` does not satisfied your requirements, try to implement similar functionality with two `DatePicker`.
 > * Use the `nzDisabledDate` property to limit the start and end dates.
-> * Improve user experience with `nzOpen` and `nzOnOpenChange`.
+> * Improve user experience with `open()`.

components/date-picker/demo/start-end.ts

@@ -1,4 +1,5 @@
-import { Component } from '@angular/core';
+import { Component, ViewChild } from '@angular/core';
+import { NzDatePickerComponent } from 'ng-zorro-antd/date-picker';
 
 @Component({
   selector: 'nz-demo-date-picker-start-end',
@@ -9,21 +10,17 @@ import { Component } from '@angular/core';
       nzFormat="yyyy-MM-dd HH:mm:ss"
       [(ngModel)]="startValue"
       nzPlaceHolder="Start"
-      (ngModelChange)="onStartChange($event)"
       (nzOnOpenChange)="handleStartOpenChange($event)"
-    >
-    </nz-date-picker>
+    ></nz-date-picker>
     <nz-date-picker
+      #endDatePicker
       [nzDisabledDate]="disabledEndDate"
       nzShowTime
       nzFormat="yyyy-MM-dd HH:mm:ss"
       [(ngModel)]="endValue"
       nzPlaceHolder="End"
-      [nzOpen]="endOpen"
-      (ngModelChange)="onEndChange($event)"
       (nzOnOpenChange)="handleEndOpenChange($event)"
-    >
-    </nz-date-picker>
+    ></nz-date-picker>
   `,
   styles: [
     `
@@ -36,7 +33,7 @@ import { Component } from '@angular/core';
 export class NzDemoDatePickerStartEndComponent {
   startValue: Date | null = null;
   endValue: Date | null = null;
-  endOpen = false;
+  @ViewChild('endDatePicker') endDatePicker!: NzDatePickerComponent;
 
   disabledStartDate = (startValue: Date): boolean => {
     if (!startValue || !this.endValue) {
@@ -52,23 +49,14 @@ export class NzDemoDatePickerStartEndComponent {
     return endValue.getTime() <= this.startValue.getTime();
   };
 
-  onStartChange(date: Date): void {
-    this.startValue = date;
-  }
-
-  onEndChange(date: Date): void {
-    this.endValue = date;
-  }
-
   handleStartOpenChange(open: boolean): void {
     if (!open) {
-      this.endOpen = true;
+      this.endDatePicker.open();
     }
-    console.log('handleStartOpenChange', open, this.endOpen);
+    console.log('handleStartOpenChange', open);
   }
 
   handleEndOpenChange(open: boolean): void {
-    console.log(open);
-    this.endOpen = open;
+    console.log('handleEndOpenChange', open);
   }
 }

components/date-picker/doc/index.en-US.md

@@ -38,7 +38,7 @@ There are five kinds of picker:
 
 ### Common API
 
-The following APIs are shared by nz-date-picker, nz-month-picker, nz-range-picker, nz-week-picker.
+The following APIs are shared by nz-date-picker, nz-year-picker, nz-month-picker, nz-week-picker, nz-range-picker.
 
 | Property | Description | Type | Default | Global Config |
 | -------- | ----------- | ---- | ------- | - |
@@ -49,14 +49,20 @@ The following APIs are shared by nz-date-picker, nz-month-picker, nz-range-picke
 | `[nzInputReadOnly]` | set the readonly attribute of the input tag (avoids virtual keyboard on touch devices) | `boolean` | `false` | - |
 | `[nzDisabledDate]` | specify the date that cannot be selected | `(current: Date) => boolean` | - | - |
 | `[nzLocale]` | localization configuration | `object` | [default](https://github.com/ant-design/ant-design/blob/master/components/date-picker/locale/example.json) | - |
-| `[nzOpen]` | open state of picker | `boolean` | - | - |
 | `[nzPopupStyle]` | to customize the style of the popup calendar | `object` | `{}` | - |
 | `[nzDropdownClassName]` | to customize the className of the popup calendar  | `string` | - | - |
 | `[nzSize]` | determine the size of the input box, the height of `large` and `small`, are 40px and 24px respectively, while default size is 32px | `'large' \| 'small'` | - | - |
 | `[nzDefaultPickerValue]` | default picker date | `Date` \| `Date[]` | - | - |
 | `[nzSuffixIcon]` | the custom suffix icon | `string` \| `TemplateRef` | - | ✅ |
 | `(nzOnOpenChange)` | a callback emitter, can be executed whether the popup calendar is popped up or closed | `EventEmitter<boolean>` | - | - |
 
+### Common Methods
+
+| Name | Description |
+| ---- | ----------- |
+| `open()` | open calendar panel |
+| `close()` | close calendar panel |
+
 ### nz-date-picker
 
 | Property | Description | Type | Default |

components/date-picker/doc/index.zh-CN.md

@@ -38,7 +38,7 @@ registerLocaleData(zh);
 
 ### 共同的 API
 
-以下 API 为 nz-date-picker、nz-month-picker、nz-range-picker, nz-week-picker 共享的 API。
+以下 API 为 nz-date-picker、nz-year-picker、nz-month-picker、nz-week-picker、nz-range-picker 共享的 API。
 
 | 参数 | 说明 | 类型 | 默认值 | 全局配置 |
 | --- | --- | --- | --- | - |
@@ -49,14 +49,20 @@ registerLocaleData(zh);
 | `[nzInputReadOnly]` | 为 input 标签设置只读属性（避免在移动设备上触发小键盘） | `boolean` | `false` | - |
 | `[nzDisabledDate]` | 不可选择的日期 | `(current: Date) => boolean` | - | - |
 | `[nzLocale]` | 国际化配置 | `object` | [默认配置](https://github.com/ant-design/ant-design/blob/master/components/date-picker/locale/example.json) | - |
-| `[nzOpen]` | 控制弹层是否展开 | `boolean` | - | - |
 | `[nzPopupStyle]` | 额外的弹出日历样式 | `object` | `{}` | - |
 | `[nzDropdownClassName]` | 额外的弹出日历 className | `string` | - | - |
 | `[nzSize]` | 输入框大小，`large` 高度为 40px，`small` 为 24px，默认是 32px | `'large' \| 'small'` | - | - |
 | `[nzDefaultPickerValue]` | 默认面板日期 | `Date` \| `Date[]` | - | - |
 | `[nzSuffixIcon]` | 自定义的后缀图标 | `string` \| `TemplateRef` | - | ✅ |
 | `(nzOnOpenChange)` | 弹出日历和关闭日历的回调 | `EventEmitter<boolean>` | - | - |
 
+### 共同的方法
+
+| 名称 | 描述 |
+| ---- | ----------- |
+| `open()` | 打开日历弹层 |
+| `close()` | 关闭日历弹层 |
+
 ### nz-date-picker
 
 | 参数 | 说明 | 类型 | 默认值 |

components/date-picker/picker.component.ts

@@ -328,7 +328,7 @@ export class NzPickerComponent implements OnInit, AfterViewInit, OnChanges, OnDe
 
   // Show overlay content
   showOverlay(): void {
-    if (!this.realOpenState) {
+    if (!this.realOpenState && !this.disabled) {
       this.resetInputWidthAndArrowLeft();
       this.overlayOpen = true;
       this.animationStart();
@@ -351,7 +351,7 @@ export class NzPickerComponent implements OnInit, AfterViewInit, OnChanges, OnDe
   onClickInputBox(event: MouseEvent, partType?: RangePartType): void {
     event.stopPropagation();
 
-    if (!this.disabled && !this.isOpenHandledByUser()) {
+    if (!this.isOpenHandledByUser()) {
       this.showOverlay();
     }
     this.onFocus(partType);