feat(popup): expose popper instance through getPopper method (#6096)

* feat(popup): expose `popper` instance through `getPopper` method

* feat(popup): 添加 `getPopper` 方法以获取当前组件的 popper 实例，并更新相关文档

* docs(popup): 修正 `getPopper` 方法的类型描述，去除多余空格

* fix(popup): 更新 `getPopper` 方法的返回类型为 `Instance`

* fix(popup): 更新 `getOverlay` 和 `getPopper` 方法的返回类型为 `HTMLElement | null` 和 `Instance | null`

* chore: stash changelog [ci skip]

* chore: stash changelog [ci skip]

---------

Co-authored-by: tdesign-bot <[email protected]>

Author: RSS1102

packages/components/popup/popup.en-US.md

@@ -1,6 +1,7 @@
 :: BASE_DOC ::
 
 ## API
+
 ### Popup Props
 
 name | type | default | description | required
@@ -42,6 +43,7 @@ visible-change | `(visible: boolean, context: PopupVisibleChangeContext)` | [see
 
 name | params | return | description
 -- | -- | -- | --
-getOverlay | \- | `HTMLElement` | used to get overly html element
+getOverlay | \- | `HTMLElement \| null` | used to get overly html element
 getOverlayState | \- | `{ hover: boolean }` | get mouseover state of overlay
+getPopper | \- | `Instance \| null` | get the popup component popper instance。[see more ts definition](https://github.com/Tencent/tdesign-vue-next/blob/develop/packages/components/popup/type.ts)。<br/>`import { Instance } from '@popperjs/core'`<br/>
 update | \- | \- | used to update overlay content

packages/components/popup/popup.md

@@ -37,11 +37,12 @@
 如果您不确定问题是否是由该规则引起的，或者确定该规则不是问题的根本原因，请在 `GitHub` 上提出一个 `issue`，并提供可以重现问题的代码。这将有助于我们更好地了解您的问题并提供更好的帮助。
 
 ## API
+
 ### Popup Props
 
-名称 | 类型 | 默认值 | 说明 | 必传
+名称 | 类型 | 默认值 | 描述 | 必传
 -- | -- | -- | -- | --
-attach | String / Function | 'body' | 制定挂载节点。数据类型为 String 时，会被当作选择器处理，进行节点查询。示例：'body' 或 () => document.body。TS 类型：`AttachNode`。[通用类型定义](https://github.com/Tencent/tdesign-vue-next/blob/develop/packages/components/common.ts) | N
+attach | String / Function | 'body' | 指定挂载节点。数据类型为 String 时，会被当作选择器处理，进行节点查询。示例：'body' 或 () => document.body。TS 类型：`AttachNode`。[通用类型定义](https://github.com/Tencent/tdesign-vue-next/blob/develop/packages/components/common.ts) | N
 content | String / Slot / Function | - | 浮层里面的内容。TS 类型：`string \| TNode`。[通用类型定义](https://github.com/Tencent/tdesign-vue-next/blob/develop/packages/components/common.ts) | N
 default | String / Slot / Function | - | 触发元素，同 triggerElement。TS 类型：`string \| TNode`。[通用类型定义](https://github.com/Tencent/tdesign-vue-next/blob/develop/packages/components/common.ts) | N
 delay | Number / Array | - | 延时显示或隐藏浮层，[延迟显示的时间，延迟隐藏的时间]，单位：毫秒。如果只有一个时间，则表示显示和隐藏的延迟时间相同。示例 `'300'` 或者 `[200, 200]`。默认为：[250, 150]。TS 类型：`number \| Array<number>` | N
@@ -78,6 +79,7 @@ visible-change | `(visible: boolean, context: PopupVisibleChangeContext)` | 当
 
 名称 | 参数 | 返回值 | 描述
 -- | -- | -- | --
-getOverlay | \- | `HTMLElement` | 获取浮层元素
+getOverlay | \- | `HTMLElement \| null` | 获取浮层元素
 getOverlayState | \- | `{ hover: boolean }` | 获取浮层悬浮状态
+getPopper | \- | `Instance \| null` | 获取当前组件 popper 实例。[详细类型定义](https://github.com/Tencent/tdesign-vue-next/blob/develop/packages/components/popup/type.ts)。<br/>`import { Instance } from '@popperjs/core'`<br/>
 update | \- | \- | 更新浮层内容

packages/components/popup/popup.tsx

@@ -249,6 +249,7 @@ export default defineComponent({
       getOverlayState: () => ({
         hover: isOverlayHover.value,
       }),
+      getPopper: () => popper,
       /** close is going to be deprecated. visible is enough */
       close: () => hide(),
     });

packages/components/popup/props.ts

@@ -8,7 +8,7 @@ import { TdPopupProps } from './type';
 import { PropType } from 'vue';
 
 export default {
-  /** 制定挂载节点。数据类型为 String 时，会被当作选择器处理，进行节点查询。示例：'body' 或 () => document.body */
+  /** 指定挂载节点。数据类型为 String 时，会被当作选择器处理，进行节点查询。示例：'body' 或 () => document.body */
   attach: {
     type: [String, Function] as PropType<TdPopupProps['attach']>,
     default: 'body' as TdPopupProps['attach'],

packages/components/popup/type.ts

@@ -4,11 +4,12 @@
  * 该文件为脚本自动生成文件，请勿随意修改。如需修改请联系 PMC
  * */
 
+import { Instance } from '@popperjs/core';
 import { TNode, ClassName, Styles, AttachNode } from '../common';
 
 export interface TdPopupProps {
   /**
-   * 制定挂载节点。数据类型为 String 时，会被当作选择器处理，进行节点查询。示例：'body' 或 () => document.body
+   * 指定挂载节点。数据类型为 String 时，会被当作选择器处理，进行节点查询。示例：'body' 或 () => document.body
    * @default 'body'
    */
   attach?: AttachNode;
@@ -116,11 +117,15 @@ export interface PopupInstanceFunctions {
   /**
    * 获取浮层元素
    */
-  getOverlay?: () => HTMLElement;
+  getOverlay?: () => HTMLElement | null;
   /**
    * 获取浮层悬浮状态
    */
   getOverlayState?: () => { hover: boolean };
+  /**
+   * 获取当前组件 popper 实例
+   */
+  getPopper?: () => Instance | null;
   /**
    * 更新浮层内容
    */

packages/tdesign-vue-next/.changelog/pr-6096.md

@@ -0,0 +1,6 @@
+---
+pr_number: 6096
+contributor: RSS1102
+---
+
+- feat(popup): 新增 `getPopper()` 方法，将返回 popper 实例，用于基于 popper 进行动态操作的场景 @RSS1102 ([#6096](https://github.com/Tencent/tdesign-vue-next/pull/6096))