From cf6af533f7968d2182099f6e2b46cf44276356d7 Mon Sep 17 00:00:00 2001
From: RSS1102 <jimmyrss1102@gmail.com>
Date: Wed, 29 Oct 2025 15:15:15 +0800
Subject: [PATCH 1/4] feat(popup): add multiple instance methods to popup
 component

---
 src/popup/popup.en-US.md | 11 ++++++++++-
 src/popup/popup.md       | 19 ++++++++++---------
 src/popup/popup.tsx      | 29 +++++++++++++++++++++++++++--
 src/popup/type.ts        | 26 ++++++++++++++++++++++++++
 4 files changed, 73 insertions(+), 12 deletions(-)

diff --git a/src/popup/popup.en-US.md b/src/popup/popup.en-US.md
index 0155888d1..01aa55b8b 100644
--- a/src/popup/popup.en-US.md
+++ b/src/popup/popup.en-US.md
@@ -45,4 +45,13 @@ name | params | default | description
 -- | -- | -- | --
 content | String / Slot / Function | - | required。Typescript：`string \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts)
 popupProps | Object | - | \-
-triggerElement | String | - | required
\ No newline at end of file
+triggerElement | String | - | required
+
+### PopupInstanceFunctions 组件实例方法
+
+name | params | return | description
+-- | -- | -- | --
+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/tree/develop/src/popup/type.ts)。<br/>`import { Instance } from '@popperjs/core'`<br/>
+update | \- | \- | used to update overlay content
diff --git a/src/popup/popup.md b/src/popup/popup.md
index 200d3e6c9..94d471e3a 100644
--- a/src/popup/popup.md
+++ b/src/popup/popup.md
@@ -35,24 +35,25 @@ triggerElement | String / Slot / Function | - | 触发元素。值类型为字
 visible | Boolean | - | 是否显示浮层。支持语法糖 `v-model`。TS 类型：`boolean` | N
 defaultVisible | Boolean | - | 是否显示浮层。非受控属性。TS 类型：`boolean` | N
 zIndex | Number | - | 组件层级，Web 侧样式默认为 5500，移动端和小程序样式默认为 1500 | N
+onOverlayClick | Function |  | TS 类型：`(context: { e: MouseEvent }) => void`<br/>内容面板点击时触发 | N
 onScroll | Function |  | TS 类型：`(context: { e: WheelEvent }) => void`<br/>下拉选项滚动事件 | N
 onScrollToBottom | Function |  | TS 类型：`(context: { e: WheelEvent }) => void`<br/>下拉滚动触底事件，常用于滚动到底执行具体业务逻辑 | N
-onVisibleChange | Function |  | TS 类型：`(visible: boolean, context: PopupVisibleChangeContext) => void`<br/>当浮层隐藏或显示时触发，`trigger=document` 表示点击非浮层元素触发；`trigger=context-menu` 表示右击触发。[详细类型定义](https://github.com/Tencent/tdesign-vue/tree/develop/src/popup/type.ts)。<br/>`interface PopupVisibleChangeContext { e?: PopupTriggerEvent; trigger?: PopupTriggerSource }`<br/><br/>`type PopupTriggerEvent = MouseEvent \| FocusEvent \| KeyboardEvent`<br/><br/>`type PopupTriggerSource = 'document' \| 'trigger-element-click' \| 'trigger-element-hover' \| 'trigger-element-blur' \| 'trigger-element-focus' \| 'trigger-element-mousedown' \| 'context-menu' \| 'keydown-esc'`<br/> | N
+onVisibleChange | Function |  | TS 类型：`(visible: boolean, context: PopupVisibleChangeContext) => void`<br/>当浮层隐藏或显示时触发，`trigger=document` 表示点击非浮层元素触发；`trigger=context-menu` 表示右击触发。[详细类型定义](https://github.com/Tencent/tdesign-vue/tree/develop/src/popup/type.ts)。<br/>`interface PopupVisibleChangeContext { e?: PopupTriggerEvent; trigger?: PopupTriggerSource }`<br/><br/>`type PopupTriggerEvent = MouseEvent \| FocusEvent \| KeyboardEvent`<br/><br/>`type PopupTriggerSource = 'document' \| 'trigger-element-click' \| 'trigger-element-hover' \| 'trigger-element-blur' \| 'trigger-element-focus' \| 'trigger-element-mousedown' \| 'trigger-element-close' \| 'context-menu' \| 'keydown-esc'`<br/> | N
 
 ### Popup Events
 
 名称 | 参数 | 描述
 -- | -- | --
+overlay-click | `(context: { e: MouseEvent })` | 内容面板点击时触发
 scroll | `(context: { e: WheelEvent })` | 下拉选项滚动事件
 scroll-to-bottom | `(context: { e: WheelEvent })` | 下拉滚动触底事件，常用于滚动到底执行具体业务逻辑
-visible-change | `(visible: boolean, context: PopupVisibleChangeContext)` | 当浮层隐藏或显示时触发，`trigger=document` 表示点击非浮层元素触发；`trigger=context-menu` 表示右击触发。[详细类型定义](https://github.com/Tencent/tdesign-vue/tree/develop/src/popup/type.ts)。<br/>`interface PopupVisibleChangeContext { e?: PopupTriggerEvent; trigger?: PopupTriggerSource }`<br/><br/>`type PopupTriggerEvent = MouseEvent \| FocusEvent \| KeyboardEvent`<br/><br/>`type PopupTriggerSource = 'document' \| 'trigger-element-click' \| 'trigger-element-hover' \| 'trigger-element-blur' \| 'trigger-element-focus' \| 'trigger-element-mousedown' \| 'context-menu' \| 'keydown-esc'`<br/>
+visible-change | `(visible: boolean, context: PopupVisibleChangeContext)` | 当浮层隐藏或显示时触发，`trigger=document` 表示点击非浮层元素触发；`trigger=context-menu` 表示右击触发。[详细类型定义](https://github.com/Tencent/tdesign-vue/tree/develop/src/popup/type.ts)。<br/>`interface PopupVisibleChangeContext { e?: PopupTriggerEvent; trigger?: PopupTriggerSource }`<br/><br/>`type PopupTriggerEvent = MouseEvent \| FocusEvent \| KeyboardEvent`<br/><br/>`type PopupTriggerSource = 'document' \| 'trigger-element-click' \| 'trigger-element-hover' \| 'trigger-element-blur' \| 'trigger-element-focus' \| 'trigger-element-mousedown' \| 'trigger-element-close' \| 'context-menu' \| 'keydown-esc'`<br/>
 
-### PopupPlugin
+### PopupInstanceFunctions 组件实例方法
 
-同时也支持 `this.$popup`。
-
-参数名称 | 参数类型 | 参数默认值 | 参数说明
+名称 | 参数 | 返回值 | 描述
 -- | -- | -- | --
-content | String / Slot / Function | - | 必需。气泡框的内容。TS 类型：`string \| TNode`。[通用类型定义](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts)
-popupProps | Object | - | 透传气泡框/浮层的属性
-triggerElement | String | - | 必需。触发气泡框/浮层的元素，传入选择器即可
\ No newline at end of file
+getOverlay | \- | `HTMLElement \| null` | 获取浮层元素
+getOverlayState | \- | `{ hover: boolean }` | 获取浮层悬浮状态
+getPopper | \- | `Instance \| null` | 获取当前组件 popper 实例。[详细类型定义](https://github.com/Tencent/tdesign-vue/tree/develop/src/popup/type.ts)。<br/>`import { Instance } from '@popperjs/core'`<br/>
+update | \- | \- | 更新浮层内容
diff --git a/src/popup/popup.tsx b/src/popup/popup.tsx
index 7e5ef5ee7..1623e7195 100644
--- a/src/popup/popup.tsx
+++ b/src/popup/popup.tsx
@@ -1,5 +1,5 @@
 import { VNodeDirective } from 'vue';
-import { createPopper } from '@popperjs/core';
+import { createPopper, Instance as PopperInstance } from '@popperjs/core';
 import { debounce } from 'lodash-es';
 import { on, off, once } from '../utils/dom';
 import { renderTNodeJSX, renderContent } from '../utils/render-tnode';
@@ -49,7 +49,7 @@ export default mixins(classPrefixMixins, getAttachConfigMixins('popup')).extend(
   data() {
     return {
       /** popperjs instance */
-      popper: null as ReturnType<typeof createPopper>,
+      popper: null as PopperInstance,
       /** timeout id */
       timeout: null,
       hasDocumentEvent: false,
@@ -60,6 +60,8 @@ export default mixins(classPrefixMixins, getAttachConfigMixins('popup')).extend(
       contentClicked: false,
       /** is popup leaving */
       isLeaving: false,
+      /** is overlay hover */
+      isOverlayHover: false,
     };
   },
   computed: {
@@ -231,6 +233,27 @@ export default mixins(classPrefixMixins, getAttachConfigMixins('popup')).extend(
         this.updateScrollTop?.(overlayEl);
       }
     },
+    // PopupInstanceFunctions: 获取浮层元素
+    getOverlay(): HTMLElement | null {
+      const overlayEl = this.$refs?.overlay as HTMLElement;
+      return overlayEl;
+    },
+
+    // PopupInstanceFunctions: 获取浮层悬浮状态
+    getOverlayState(): { hover: boolean } {
+      return { hover: this.isOverlayHover };
+    },
+
+    // PopupInstanceFunctions: 获取 Popper 实例
+    getPopper(): PopperInstance | null {
+      return this.popper;
+    },
+
+    // PopupInstanceFunctions: 更新浮层内容
+    update() {
+      this.updatePopper();
+    },
+
     getOverlayStyle() {
       const { overlayStyle } = this;
       const triggerEl = this.$el as HTMLElement;
@@ -334,6 +357,7 @@ export default mixins(classPrefixMixins, getAttachConfigMixins('popup')).extend(
       }
     },
     onMouseEnter() {
+      this.isOverlayHover = true;
       if (this.destroyOnClose && this.isLeaving) {
         // 如果 popup 在关闭的时候会被销毁，那在它消失的过程中，不响应鼠标进入事件，因为否则不会触发 mouseleave
         return;
@@ -342,6 +366,7 @@ export default mixins(classPrefixMixins, getAttachConfigMixins('popup')).extend(
       this.handleOpen({});
     },
     onMouseLeave(ev: MouseEvent) {
+      this.isOverlayHover = false;
       // 子元素存在打开的 popup 时，ui 可能重叠，而 dom 节点多是并列关系
       // 需要做碰撞检测去阻止父级 popup 关闭
       if (this.visibleState > 1) {
diff --git a/src/popup/type.ts b/src/popup/type.ts
index ea190d68f..113b4277b 100644
--- a/src/popup/type.ts
+++ b/src/popup/type.ts
@@ -4,6 +4,7 @@
  * 该文件为脚本自动生成文件，请勿随意修改。如需修改请联系 PMC
  * */
 
+import { Instance } from '@popperjs/core';
 import { TNode, ClassName, Styles, AttachNode } from '../common';
 
 export interface TdPopupProps {
@@ -89,6 +90,10 @@ export interface TdPopupProps {
    * 组件层级，Web 侧样式默认为 5500，移动端和小程序样式默认为 1500
    */
   zIndex?: number;
+  /**
+   * 内容面板点击时触发
+   */
+  onOverlayClick?: (context: { e: MouseEvent }) => void;
   /**
    * 下拉选项滚动事件
    */
@@ -103,6 +108,26 @@ export interface TdPopupProps {
   onVisibleChange?: (visible: boolean, context: PopupVisibleChangeContext) => void;
 }
 
+/** 组件实例方法 */
+export interface PopupInstanceFunctions {
+  /**
+   * 获取浮层元素
+   */
+  getOverlay?: () => HTMLElement | null;
+  /**
+   * 获取浮层悬浮状态
+   */
+  getOverlayState?: () => { hover: boolean };
+  /**
+   * 获取当前组件 popper 实例
+   */
+  getPopper?: () => Instance | null;
+  /**
+   * 更新浮层内容
+   */
+  update?: () => void;
+}
+
 export type PopupPlacement =
   | 'top'
   | 'left'
@@ -131,5 +156,6 @@ export type PopupTriggerSource =
   | 'trigger-element-blur'
   | 'trigger-element-focus'
   | 'trigger-element-mousedown'
+  | 'trigger-element-close'
   | 'context-menu'
   | 'keydown-esc';

From 80e995dd0263a1156b871367a7648be84de99cfc Mon Sep 17 00:00:00 2001
From: RSS1102 <jimmyrss1102@gmail.com>
Date: Wed, 29 Oct 2025 15:22:21 +0800
Subject: [PATCH 2/4] =?UTF-8?q?fix(popup):=20=E4=BF=AE=E6=AD=A3=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3=E4=B8=AD=20onVisibleChange=20=E5=92=8C=20visible-chan?=
 =?UTF-8?q?ge=20=E7=9A=84=E6=8F=8F=E8=BF=B0=E6=A0=BC=E5=BC=8F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/popup/popup.md | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/src/popup/popup.md b/src/popup/popup.md
index 94d471e3a..705302399 100644
--- a/src/popup/popup.md
+++ b/src/popup/popup.md
@@ -38,7 +38,7 @@ zIndex | Number | - | 组件层级，Web 侧样式默认为 5500，移动端和
 onOverlayClick | Function |  | TS 类型：`(context: { e: MouseEvent }) => void`<br/>内容面板点击时触发 | N
 onScroll | Function |  | TS 类型：`(context: { e: WheelEvent }) => void`<br/>下拉选项滚动事件 | N
 onScrollToBottom | Function |  | TS 类型：`(context: { e: WheelEvent }) => void`<br/>下拉滚动触底事件，常用于滚动到底执行具体业务逻辑 | N
-onVisibleChange | Function |  | TS 类型：`(visible: boolean, context: PopupVisibleChangeContext) => void`<br/>当浮层隐藏或显示时触发，`trigger=document` 表示点击非浮层元素触发；`trigger=context-menu` 表示右击触发。[详细类型定义](https://github.com/Tencent/tdesign-vue/tree/develop/src/popup/type.ts)。<br/>`interface PopupVisibleChangeContext { e?: PopupTriggerEvent; trigger?: PopupTriggerSource }`<br/><br/>`type PopupTriggerEvent = MouseEvent \| FocusEvent \| KeyboardEvent`<br/><br/>`type PopupTriggerSource = 'document' \| 'trigger-element-click' \| 'trigger-element-hover' \| 'trigger-element-blur' \| 'trigger-element-focus' \| 'trigger-element-mousedown' \| 'trigger-element-close' \| 'context-menu' \| 'keydown-esc'`<br/> | N
+onVisibleChange | Function |  | TS 类型：`(visible: boolean, context: PopupVisibleChangeContext) => void`<br/>当浮层隐藏或显示时触发，`trigger=document` 表示点击非浮层元素触发；`trigger=context-menu` 表示右击触发。[详细类型定义](https://github.com/Tencent/tdesign-vue/tree/develop/src/popup/type.ts)。<br/>`interface PopupVisibleChangeContext { e?: PopupTriggerEvent; trigger?: PopupTriggerSource }`<br/><br/>`type PopupTriggerEvent = MouseEvent \| FocusEvent \| KeyboardEvent`<br/><br/>`type PopupTriggerSource = 'document' \| 'trigger-element-click' \| 'trigger-element-hover' \| 'trigger-element-blur' \| 'trigger-element-focus' \| 'trigger-element-mousedown' \| 'context-menu' \| 'keydown-esc'`<br/> | N
 
 ### Popup Events
 
@@ -47,7 +47,17 @@ onVisibleChange | Function |  | TS 类型：`(visible: boolean, context: PopupVi
 overlay-click | `(context: { e: MouseEvent })` | 内容面板点击时触发
 scroll | `(context: { e: WheelEvent })` | 下拉选项滚动事件
 scroll-to-bottom | `(context: { e: WheelEvent })` | 下拉滚动触底事件，常用于滚动到底执行具体业务逻辑
-visible-change | `(visible: boolean, context: PopupVisibleChangeContext)` | 当浮层隐藏或显示时触发，`trigger=document` 表示点击非浮层元素触发；`trigger=context-menu` 表示右击触发。[详细类型定义](https://github.com/Tencent/tdesign-vue/tree/develop/src/popup/type.ts)。<br/>`interface PopupVisibleChangeContext { e?: PopupTriggerEvent; trigger?: PopupTriggerSource }`<br/><br/>`type PopupTriggerEvent = MouseEvent \| FocusEvent \| KeyboardEvent`<br/><br/>`type PopupTriggerSource = 'document' \| 'trigger-element-click' \| 'trigger-element-hover' \| 'trigger-element-blur' \| 'trigger-element-focus' \| 'trigger-element-mousedown' \| 'trigger-element-close' \| 'context-menu' \| 'keydown-esc'`<br/>
+visible-change | `(visible: boolean, context: PopupVisibleChangeContext)` | 当浮层隐藏或显示时触发，`trigger=document` 表示点击非浮层元素触发；`trigger=context-menu` 表示右击触发。[详细类型定义](https://github.com/Tencent/tdesign-vue/tree/develop/src/popup/type.ts)。<br/>`interface PopupVisibleChangeContext { e?: PopupTriggerEvent; trigger?: PopupTriggerSource }`<br/><br/>`type PopupTriggerEvent = MouseEvent \| FocusEvent \| KeyboardEvent`<br/><br/>`type PopupTriggerSource = 'document' \| 'trigger-element-click' \| 'trigger-element-hover' \| 'trigger-element-blur' \| 'trigger-element-focus' \| 'trigger-element-mousedown' \| 'context-menu' \| 'keydown-esc'`<br/>
+
+### PopupPlugin
+
+同时也支持 `this.$popup`。
+
+名称 | 参数 | 返回值 | 描述
+-- | -- | -- | --
+content | String / Slot / Function | - | 必需。气泡框的内容。TS 类型：`string \| TNode`。[通用类型定义](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts)
+popupProps | Object | - | 透传气泡框/浮层的属性
+triggerElement | String | - | 必需。触发气泡框/浮层的元素，传入选择器即可
 
 ### PopupInstanceFunctions 组件实例方法
 

From 4a1ecbc0934d4ec463f5053944339b2baa4b339d Mon Sep 17 00:00:00 2001
From: RSS1102 <jimmyrss1102@gmail.com>
Date: Wed, 29 Oct 2025 15:23:21 +0800
Subject: [PATCH 3/4] =?UTF-8?q?fix(popup):=20=E7=A7=BB=E9=99=A4=20onOverla?=
 =?UTF-8?q?yClick=20=E5=92=8C=20overlay-click=20=E7=9A=84=E6=8F=8F?=
 =?UTF-8?q?=E8=BF=B0=EF=BC=8C=E4=BF=AE=E6=AD=A3=20API=20=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/popup/popup.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/src/popup/popup.md b/src/popup/popup.md
index 705302399..027aee635 100644
--- a/src/popup/popup.md
+++ b/src/popup/popup.md
@@ -35,7 +35,6 @@ triggerElement | String / Slot / Function | - | 触发元素。值类型为字
 visible | Boolean | - | 是否显示浮层。支持语法糖 `v-model`。TS 类型：`boolean` | N
 defaultVisible | Boolean | - | 是否显示浮层。非受控属性。TS 类型：`boolean` | N
 zIndex | Number | - | 组件层级，Web 侧样式默认为 5500，移动端和小程序样式默认为 1500 | N
-onOverlayClick | Function |  | TS 类型：`(context: { e: MouseEvent }) => void`<br/>内容面板点击时触发 | N
 onScroll | Function |  | TS 类型：`(context: { e: WheelEvent }) => void`<br/>下拉选项滚动事件 | N
 onScrollToBottom | Function |  | TS 类型：`(context: { e: WheelEvent }) => void`<br/>下拉滚动触底事件，常用于滚动到底执行具体业务逻辑 | N
 onVisibleChange | Function |  | TS 类型：`(visible: boolean, context: PopupVisibleChangeContext) => void`<br/>当浮层隐藏或显示时触发，`trigger=document` 表示点击非浮层元素触发；`trigger=context-menu` 表示右击触发。[详细类型定义](https://github.com/Tencent/tdesign-vue/tree/develop/src/popup/type.ts)。<br/>`interface PopupVisibleChangeContext { e?: PopupTriggerEvent; trigger?: PopupTriggerSource }`<br/><br/>`type PopupTriggerEvent = MouseEvent \| FocusEvent \| KeyboardEvent`<br/><br/>`type PopupTriggerSource = 'document' \| 'trigger-element-click' \| 'trigger-element-hover' \| 'trigger-element-blur' \| 'trigger-element-focus' \| 'trigger-element-mousedown' \| 'context-menu' \| 'keydown-esc'`<br/> | N
@@ -44,7 +43,6 @@ onVisibleChange | Function |  | TS 类型：`(visible: boolean, context: PopupVi
 
 名称 | 参数 | 描述
 -- | -- | --
-overlay-click | `(context: { e: MouseEvent })` | 内容面板点击时触发
 scroll | `(context: { e: WheelEvent })` | 下拉选项滚动事件
 scroll-to-bottom | `(context: { e: WheelEvent })` | 下拉滚动触底事件，常用于滚动到底执行具体业务逻辑
 visible-change | `(visible: boolean, context: PopupVisibleChangeContext)` | 当浮层隐藏或显示时触发，`trigger=document` 表示点击非浮层元素触发；`trigger=context-menu` 表示右击触发。[详细类型定义](https://github.com/Tencent/tdesign-vue/tree/develop/src/popup/type.ts)。<br/>`interface PopupVisibleChangeContext { e?: PopupTriggerEvent; trigger?: PopupTriggerSource }`<br/><br/>`type PopupTriggerEvent = MouseEvent \| FocusEvent \| KeyboardEvent`<br/><br/>`type PopupTriggerSource = 'document' \| 'trigger-element-click' \| 'trigger-element-hover' \| 'trigger-element-blur' \| 'trigger-element-focus' \| 'trigger-element-mousedown' \| 'context-menu' \| 'keydown-esc'`<br/>

From bd545bd58a99dcc47bf740cc55c3747d95ebc65d Mon Sep 17 00:00:00 2001
From: RSS1102 <jimmyrss1102@gmail.com>
Date: Wed, 29 Oct 2025 15:33:07 +0800
Subject: [PATCH 4/4] =?UTF-8?q?fix(popup):=20=E7=A7=BB=E9=99=A4=E6=97=A0?=
 =?UTF-8?q?=E6=95=88=E7=9A=84=E8=A7=A6=E5=8F=91=E6=BA=90=20'trigger-elemen?=
 =?UTF-8?q?t-close'?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/popup/type.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/popup/type.ts b/src/popup/type.ts
index 113b4277b..8b3817b9d 100644
--- a/src/popup/type.ts
+++ b/src/popup/type.ts
@@ -156,6 +156,5 @@ export type PopupTriggerSource =
   | 'trigger-element-blur'
   | 'trigger-element-focus'
   | 'trigger-element-mousedown'
-  | 'trigger-element-close'
   | 'context-menu'
   | 'keydown-esc';