fix(module:tooltip): replace public api with more specific ones (#5449)

* fix(module:tooltip): replace public api with more specific ones #5365

* refactor(module:tooltip): refactor complex method ngOnChanges

* fix(module:tooltip): fix warnDeprecationByChanges

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

@@ -26,7 +26,7 @@ import { NzPopconfirmModule } from 'ng-zorro-antd/popconfirm';
 | `[nzPopconfirmTrigger]` | Popconfirm trigger mode. If set to `null` it would not be triggered | `'click' \| 'focus' \| 'hover' \| null` | `'hover'` |
 | `[nzPopconfirmPlacement]` | The position of the popconfirm relative to the target | `'top' \| 'left' \| 'right' \| 'bottom' \| 'topLeft' \| 'topRight' \| 'bottomLeft' \| 'bottomRight' \| 'leftTop' \| 'leftBottom' \| 'rightTop' \| 'rightBottom'` | `'top'` |
 | `[nzPopconfirmOrigin]` | Origin of the popconfirm | `ElementRef` | - |
-
+| `[nzPopconfirmVisible]` | Show or hide popconfirm | `boolean` | `false` |
 
 | Param | Description | Type | Default value |
 | ----- | ----------- | ---- | ------------- |
@@ -37,6 +37,7 @@ import { NzPopconfirmModule } from 'ng-zorro-antd/popconfirm';
 | `[nzIcon]` | Customize icon of confirmation  | `string \| TemplateRef<void>` | - |
 | `(nzOnCancel)` | Callback of cancel | `EventEmitter<void>` | - |
 | `(nzOnConfirm)` | Callback of confirmation | `EventEmitter<void>` | - |
+| `(nzPopconfirmVisibleChange)` | Callback of hide or show | `EventEmitter<boolean>` | - |
 
 Consult [Tooltip's documentation](/components/tooltip/en#api) to find more APIs.
 

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

@@ -27,7 +27,7 @@ import { NzPopconfirmModule } from 'ng-zorro-antd/popconfirm';
 | `[nzPopconfirmTrigger]` | 触发行为，为 `null` 时不响应光标事件 | `'click' \| 'focus' \| 'hover' \| null` | `'hover'` |
 | `[nzPopconfirmPlacement]` | 气泡框位置 | `'top' \| 'left' \| 'right' \| 'bottom' \| 'topLeft' \| 'topRight' \| 'bottomLeft' \| 'bottomRight' \| 'leftTop' \| 'leftBottom' \| 'rightTop' \| 'rightBottom'` | `'top'` |
 | `[nzPopconfirmOrigin]` | 气泡框定位元素 | `ElementRef` | - |
-
+| `[nzPopconfirmVisible]` | 显示隐藏气泡框 | `boolean` | `false` |
 
 | 参数 | 说明 | 类型 | 默认值 |
 | --- | --- | --- | --- |
@@ -38,6 +38,8 @@ import { NzPopconfirmModule } from 'ng-zorro-antd/popconfirm';
 | `[nzIcon]` | 自定义弹出框的 icon  | `string \| TemplateRef<void>` | - |
 | `(nzOnCancel)` | 点击取消的回调 | `EventEmitter<void>` | - |
 | `(nzOnConfirm)` | 点击确认的回调 | `EventEmitter<void>` | - |
+| `(nzPopconfirmVisibleChange)` | 显示隐藏的事件 | `EventEmitter<boolean>` | - |
+
 
 更多属性请参考 [Tooltip](/components/tooltip/zh#api)。
 

components/popconfirm/popconfirm.spec.ts

@@ -148,4 +148,11 @@ export class NzPopconfirmTestNewComponent {
   @ViewChild('stringTemplate', { static: false }) stringTemplate!: ElementRef;
   @ViewChild('templateTemplate', { static: false }) templateTemplate!: ElementRef;
   @ViewChild('iconTemplate', { static: false }) iconTemplate!: ElementRef;
+
+  visible = false;
+  visibilityTogglingCount = 0;
+
+  onVisibleChange(): void {
+    this.visibilityTogglingCount += 1;
+  }
 }

components/popconfirm/popconfirm.ts

@@ -59,6 +59,10 @@ export class NzPopconfirmDirective extends NzTooltipBaseDirective {
    */
   @Input() nzTrigger: NzTooltipTrigger = 'click';
 
+  @Input('nzPopconfirmVisible') specificVisible?: boolean;
+
+  // tslint:disable-next-line:no-output-rename
+  @Output('nzPopconfirmVisibleChange') readonly specificVisibleChange = new EventEmitter<boolean>();
   @Output() readonly nzOnCancel = new EventEmitter<void>();
   @Output() readonly nzOnConfirm = new EventEmitter<void>();
 

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

@@ -27,7 +27,8 @@ import { NzPopoverModule } from 'ng-zorro-antd/popover';
 | `[nzPopoverTrigger]` | Popover trigger mode. If set to `null` it would not be triggered | `'click' \| 'focus' \| 'hover' \| null` | `'hover'` |
 | `[nzPopoverPlacement]` | The position of the popover relative to the target | `'top' \| 'left' \| 'right' \| 'bottom' \| 'topLeft' \| 'topRight' \| 'bottomLeft' \| 'bottomRight' \| 'leftTop' \| 'leftBottom' \| 'rightTop' \| 'rightBottom'` | `'top'` |
 | `[nzPopoverOrigin]` | Origin of the tooltip | `ElementRef` | - |
-
+| `[nzPopoverVisible]` | Show or hide popover | `boolean` | `false` |
+| `(nzPopoverVisibleChange)` | Callback of hide or show | `EventEmitter<boolean>` | - |
 
 Consult [Tooltip's documentation](/components/tooltip/en#api) to find more APIs.
 

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

@@ -28,7 +28,8 @@ import { NzPopoverModule } from 'ng-zorro-antd/popover';
 | `[nzPopoverTrigger]` | 触发行为，为 `null` 时不响应光标事件 | `'click' \| 'focus' \| 'hover' \| null` | `'hover'` |
 | `[nzPopoverPlacement]` | 气泡框位置 | `'top' \| 'left' \| 'right' \| 'bottom' \| 'topLeft' \| 'topRight' \| 'bottomLeft' \| 'bottomRight' \| 'leftTop' \| 'leftBottom' \| 'rightTop' \| 'rightBottom'` | `'top'` |
 | `[nzPopoverOrigin]` | 气泡框定位元素 | `ElementRef` | - |
-
+| `[nzPopoverVisible]` | 显示隐藏气泡框 | `boolean` | `false` |
+| `(nzPopoverVisibleChange)` | 显示隐藏的事件 | `EventEmitter<boolean>` | - |
 
 更多属性请参考 [Tooltip](/components/tooltip/zh#api)。
 

components/popover/popover.spec.ts

@@ -116,4 +116,11 @@ export class NzPopoverTestComponent {
   @ViewChild('templatePopover', { static: false }) templatePopover!: ElementRef;
   @ViewChild('templatePopover', { static: false, read: NzPopoverDirective })
   templatePopoverNzPopoverDirective!: NzPopoverDirective;
+
+  visible = false;
+  visibilityTogglingCount = 0;
+
+  onVisibleChange(): void {
+    this.visibilityTogglingCount += 1;
+  }
 }

components/popover/popover.ts

@@ -11,9 +11,11 @@ import {
   ComponentFactoryResolver,
   Directive,
   ElementRef,
+  EventEmitter,
   Host,
   Input,
   Optional,
+  Output,
   Renderer2,
   ViewContainerRef,
   ViewEncapsulation
@@ -38,6 +40,10 @@ export class NzPopoverDirective extends NzTooltipBaseDirective {
   @Input('nzPopoverTrigger') specificTrigger?: NzTooltipTrigger;
   @Input('nzPopoverPlacement') specificPlacement?: string;
   @Input('nzPopoverOrigin') specificOrigin?: ElementRef<HTMLElement>;
+  @Input('nzPopoverVisible') specificVisible?: boolean;
+
+  // tslint:disable-next-line:no-output-rename
+  @Output('nzPopoverVisibleChange') readonly specificVisibleChange = new EventEmitter<boolean>();
 
   componentFactory: ComponentFactory<NzPopoverComponent> = this.resolver.resolveComponentFactory(NzPopoverComponent);
 

components/tooltip/base.ts

@@ -39,7 +39,9 @@ export abstract class NzTooltipBaseDirective implements OnChanges, OnDestroy, Af
   specificTrigger?: NzTooltipTrigger;
   specificPlacement?: string;
   specificOrigin?: ElementRef<HTMLElement>;
+  specificVisible?: boolean;
 
+  specificVisibleChange = new EventEmitter<boolean>();
   /**
    * @deprecated 10.0.0. This is deprecated and going to be removed in 10.0.0.
    * Please use a more specific API. Like `nzTooltipTitle`.
@@ -95,18 +97,16 @@ export abstract class NzTooltipBaseDirective implements OnChanges, OnDestroy, Af
     return typeof this.specificTrigger !== 'undefined' ? this.specificTrigger : this.nzTrigger;
   }
 
-  protected needProxyProperties = [
-    'nzOverlayClassName',
-    'nzOverlayStyle',
-    'nzMouseEnterDelay',
-    'nzMouseLeaveDelay',
-    'nzVisible',
-    'noAnimation'
-  ];
+  protected get isVisible(): boolean {
+    return this.specificVisible || this.nzVisible || false;
+  }
+
+  visible = false;
+
+  protected needProxyProperties = ['nzOverlayClassName', 'nzOverlayStyle', 'nzMouseEnterDelay', 'nzMouseLeaveDelay', 'noAnimation'];
 
   @Output() readonly nzVisibleChange = new EventEmitter<boolean>();
 
-  visible = false;
   component?: NzTooltipBaseComponent;
 
   protected readonly destroy$ = new Subject<void>();
@@ -122,46 +122,52 @@ export abstract class NzTooltipBaseDirective implements OnChanges, OnDestroy, Af
     protected noAnimation?: NzNoAnimationDirective
   ) {}
 
-  ngOnChanges(changes: SimpleChanges): void {
-    const { nzTrigger, specificTrigger } = changes;
-    const trigger = specificTrigger || nzTrigger;
+  warnDeprecationByChanges(changes: SimpleChanges): void {
+    const getWarnDeprecation = (property: string, newProperty: string, comp: string = 'nz-tooltip', shared: boolean = true): string => {
+      const prefix = `'${property}' of '${comp}' is deprecated and will be removed in 10.0.0.
+      Please use '${newProperty}' instead.`;
 
-    if (trigger && !trigger.isFirstChange()) {
-      this.registerTriggers();
-    }
-
-    if (this.component) {
-      this.updateChangedProperties(changes);
-    }
+      if (shared) {
+        return `${prefix} The same with 'nz-popover' and 'nz-popconfirm'.`;
+      } else {
+        return `${prefix}`;
+      }
+    };
 
     // warn deprecated things when specific property is not given
     if (changes.nzTitle && !this.specificTitle && !this.directiveNameTitle) {
-      warnDeprecation(
-        `'nzTitle' of 'nz-tooltip' is deprecated and will be removed in 10.0.0.
-Please use 'nzTooltipTitle' instead. The same with 'nz-popover' and 'nz-popconfirm'.`
-      );
+      warnDeprecation(getWarnDeprecation('nzTitle', 'nzTooltipTitle'));
     }
 
     if (changes.nzContent && !this.specificContent) {
-      warnDeprecation(
-        `'nzContent' of 'nz-popover' is deprecated and will be removed in 10.0.0.
-Please use 'nzPopoverContent' instead.`
-      );
+      warnDeprecation(getWarnDeprecation('nzContent', 'nzPopoverContent', 'nz-popover', false));
     }
 
     if (changes.nzPlacement && !this.specificPlacement) {
-      warnDeprecation(
-        `'nzPlacement' of 'nz-tooltip' is deprecated and will be removed in 10.0.0.
-Please use 'nzTooltipContent' instead. The same with 'nz-popover' and 'nz-popconfirm'.`
-      );
+      warnDeprecation(getWarnDeprecation('nzPlacement', 'nzTooltipPlacement'));
     }
 
     if (changes.nzTrigger && !this.specificTrigger) {
-      warnDeprecation(
-        `'nzTrigger' of 'nz-tooltip' is deprecated and will be removed in 10.0.0.
-Please use 'nzTooltipTrigger' instead. The same with 'nz-popover' and 'nz-popconfirm'.`
-      );
+      warnDeprecation(getWarnDeprecation('nzTrigger', 'nzTooltipTrigger'));
+    }
+
+    if (changes.nzVisible && !this.specificVisible) {
+      warnDeprecation(getWarnDeprecation('nzVisible', 'nzTooltipVisible'));
+    }
+  }
+  ngOnChanges(changes: SimpleChanges): void {
+    const { nzTrigger, specificTrigger } = changes;
+    const trigger = specificTrigger || nzTrigger;
+
+    if (trigger && !trigger.isFirstChange()) {
+      this.registerTriggers();
     }
+
+    if (this.component) {
+      this.updateChangedProperties(changes);
+    }
+
+    this.warnDeprecationByChanges(changes);
   }
 
   ngAfterViewInit(): void {
@@ -211,6 +217,7 @@ Please use 'nzTooltipTrigger' instead. The same with 'nz-popover' and 'nz-popcon
 
     this.component.nzVisibleChange.pipe(distinctUntilChanged(), takeUntil(this.destroy$)).subscribe((visible: boolean) => {
       this.visible = visible;
+      this.specificVisibleChange.emit(visible);
       this.nzVisibleChange.emit(visible);
     });
   }
@@ -280,6 +287,7 @@ Please use 'nzTooltipTrigger' instead. The same with 'nz-popover' and 'nz-popcon
       this.updateComponentValue('nzContent', this.content);
       this.updateComponentValue('nzPlacement', this.placement);
       this.updateComponentValue('nzTrigger', this.trigger);
+      this.updateComponentValue('nzVisible', this.isVisible);
     } else {
       const c = propertiesOrChanges as SimpleChanges;
       if (c.specificTitle || c.directiveNameTitle || c.nzTitle) {
@@ -294,6 +302,9 @@ Please use 'nzTooltipTrigger' instead. The same with 'nz-popover' and 'nz-popcon
       if (c.specificPlacement || c.nzPlacement) {
         this.updateComponentValue('nzPlacement', this.placement);
       }
+      if (c.specificVisible || c.nzVisible) {
+        this.updateComponentValue('nzVisible', this.isVisible);
+      }
     }
 
     this.component?.updateByDirective();

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

@@ -25,7 +25,8 @@ import { NzToolTipModule } from 'ng-zorro-antd/tooltip';
 | `[nzTooltipTrigger]` | Tooltip trigger mode. If set to `null` it would not be triggered | `'click' \| 'focus' \| 'hover' \| null` | `'hover'` |
 | `[nzTooltipPlacement]` | The position of the tooltip relative to the target | `'top' \| 'left' \| 'right' \| 'bottom' \| 'topLeft' \| 'topRight' \| 'bottomLeft' \| 'bottomRight' \| 'leftTop' \| 'leftBottom' \| 'rightTop' \| 'rightBottom'` | `'top'` |
 | `[nzTooltipOrigin]` | Origin of the tooltip | `ElementRef` | - |
-
+| `[nzTooltipVisible]` | Show or hide tooltip | `boolean` | `false` |
+| `(nTooltipVisibleChange)` | Callback of hide or show | `EventEmitter<boolean>` | - |
 
 ### Common API
 
@@ -37,8 +38,6 @@ The following APIs are shared by `nz-tooltip`, `nz-popconfirm`, `nz-popover`.
 | `[nzMouseLeaveDelay]` | Delay in seconds, before tooltip is hidden on mouse leave | `number` | `0.1` |
 | `[nzOverlayClassName]` | Class name of the tooltip card | `string` | - |
 | `[nzOverlayStyle]` | Style of the tooltip card | `object` | - |
-| `[nzVisible]` | Whether the floating tooltip card is visible or not | `boolean` | `false` |
-| `(nzVisibleChange)` | Callback executed when visibility of the tooltip card is changed | `EventEmitter<boolean>` | - |
 
 | Method | Description |
 | --- | --- |

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

@@ -27,7 +27,8 @@ import { NzToolTipModule } from 'ng-zorro-antd/tooltip';
 | `[nzTooltipTrigger]` | 触发行为，可选 `hover/focus/click`，为 `null` 时不响应光标事件 | `'click' \| 'focus' \| 'hover' \| null` | `'hover'` |
 | `[nzTooltipPlacement]` | 气泡框位置 | `'top' \| 'left' \| 'right' \| 'bottom' \| 'topLeft' \| 'topRight' \| 'bottomLeft' \| 'bottomRight' \| 'leftTop' \| 'leftBottom' \| 'rightTop' \| 'rightBottom'` | `'top'` |
 | `[nzTooltipOrigin]` | 气泡框定位元素 | `ElementRef` | - |
-
+| `[nzTooltipVisible]` | 显示隐藏气泡框 | `boolean` | `false` |
+| `(nzTooltipVisibleChange)` | 显示隐藏的事件 | `EventEmitter<boolean>` | - |
 
 ### 共同的 API
 
@@ -39,8 +40,6 @@ import { NzToolTipModule } from 'ng-zorro-antd/tooltip';
 | `[nzMouseLeaveDelay]` | 鼠标移出后延时多少才隐藏 Tooltip，单位：秒 | `number` | `0.1` |
 | `[nzOverlayClassName]` | 卡片类名 | `string` | - |
 | `[nzOverlayStyle]` | 卡片样式 | `object` | - |
-| `[nzVisible]` | 用于手动控制浮层显隐 | `boolean` | `false` |
-| `(nzVisibleChange)` | 显示隐藏的回调 | `EventEmitter<boolean>` | - |
 
 | 方法 | 说明 |
 | --- | --- |

components/tooltip/tooltip.spec.ts

@@ -255,7 +255,14 @@ function getOverlayElementForTooltip(tooltip: NzTooltipBaseDirective): HTMLEleme
       Focus
     </a>
 
-    <a #program nz-tooltip [nzTooltipTrigger]="null" nzTitle="program" [nzVisible]="visible" (nzVisibleChange)="onVisibleChange()">
+    <a
+      #program
+      nz-tooltip
+      [nzTooltipTrigger]="null"
+      nzTitle="program"
+      [nzTooltipVisible]="visible"
+      (nzTooltipVisibleChange)="onVisibleChange()"
+    >
       Manually
     </a>
 

components/tooltip/tooltip.ts

@@ -3,6 +3,14 @@
  * found in the LICENSE file at https://github.com/NG-ZORRO/ng-zorro-antd/blob/master/LICENSE
  */
 
+/**
+ * @license
+ * Copyright Alibaba.com All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/NG-ZORRO/ng-zorro-antd/blob/master/LICENSE
+ */
+
 import {
   ChangeDetectionStrategy,
   ChangeDetectorRef,
@@ -11,9 +19,11 @@ import {
   ComponentFactoryResolver,
   Directive,
   ElementRef,
+  EventEmitter,
   Host,
   Input,
   Optional,
+  Output,
   Renderer2,
   ViewContainerRef,
   ViewEncapsulation
@@ -37,7 +47,10 @@ export class NzTooltipDirective extends NzTooltipBaseDirective {
   @Input('nzTooltipTrigger') specificTrigger?: NzTooltipTrigger;
   @Input('nzTooltipPlacement') specificPlacement?: string;
   @Input('nzTooltipOrigin') specificOrigin?: ElementRef<HTMLElement>;
+  @Input('nzTooltipVisible') specificVisible?: boolean;
 
+  // tslint:disable-next-line:no-output-rename
+  @Output('nzTooltipVisibleChange') readonly specificVisibleChange = new EventEmitter<boolean>();
   componentFactory: ComponentFactory<NzToolTipComponent> = this.resolver.resolveComponentFactory(NzToolTipComponent);
 
   constructor(