Skip to content

feat(Popup): 添加实例方法 getPopper 获取 popper 实例 #751

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Oct 30, 2025
Merged

feat(Popup): 添加实例方法 getPopper 获取 popper 实例 #751

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
b38894a
feat(Popup): 添加实例方法 `` 获取 popper 实例
RSS1102 Oct 28, 2025
52da28c
refactor: 修正换行符
RSS1102 Oct 28, 2025
e841e00
docs: 生成vue2 react 文档
liweijie0812 Oct 28, 2025
6098425
fix(api.json): 修正 event_output 字段的内容为 Instance
RSS1102 Oct 29, 2025
dd81493
docs(Popup): 更新 getPopper 返回类型为 Instance
RSS1102 Oct 29, 2025
9089bbe
fix(api.json): 更新 event_output 字段类型为 "HTMLElement | null" 和 "Instance…
RSS1102 Oct 29, 2025
4467be4
docs(Popup): 更新 getOverlay 和 getPopper 返回类型为 `HTMLElement | null` 和 `…
RSS1102 Oct 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file modified db/TDesign.db
View file
Open in desktop
Binary file not shown.
190 changes: 95 additions & 95 deletions packages/products/tdesign-vue-next/packages/components/common.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,98 +40,98 @@ export interface UploadDisplayDragEvents {
}

export type ImageEvent = Event;

/**
* 通用全局类型
* */
export type PlainObject = { [key: string]: any };

export type OptionData = {
label?: string;
value?: string | number;
} & PlainObject;

export type TreeOptionData<T = string | number> = {
children?: Array<TreeOptionData<T>> | boolean;
/** option label content */
label?: string | TNode;
/** option search text */
text?: string;
/** option value */
value?: T;
/** option node content */
content?: string | TNode;
} & PlainObject;

export type SizeEnum = 'small' | 'medium' | 'large';

export type ShapeEnum = 'circle' | 'round';

export type HorizontalAlignEnum = 'left' | 'center' | 'right';

export type VerticalAlignEnum = 'top' | 'middle' | 'bottom';

export type LayoutEnum = 'vertical' | 'horizontal';

export type ClassName = { [className: string]: any } | ClassName[] | string;

export type CSSSelector = string;

export interface KeysType {
value?: string;
label?: string;
disabled?: string;
}

export interface TreeKeysType extends KeysType {
children?: string;
}

export interface HTMLElementAttributes {
[attribute: string]: string;
}

export interface TScroll {
/**
* 表示除可视区域外，额外渲染的行数，避免快速滚动过程中，新出现的内容来不及渲染从而出现空白
* @default 20
*/
bufferSize?: number;
/**
* 表示每行内容是否同一个固定高度，仅在 `scroll.type` 为 `virtual` 时有效，该属性设置为 `true` 时，可用于简化虚拟滚动内部计算逻辑，提升性能，此时则需要明确指定 `scroll.rowHeight` 属性的值
* @default false
*/
isFixedRowHeight?: boolean;
/**
* 行高，不会给元素添加样式高度，仅作为滚动时的行高参考。一般情况不需要设置该属性。如果设置，可尽量将该属性设置为每行平均高度，从而使得滚动过程更加平滑
*/
rowHeight?: number;
/**
* 启动虚拟滚动的阈值。为保证组件收益最大化，当数据量小于阈值 `scroll.threshold` 时，无论虚拟滚动的配置是否存在，组件内部都不会开启虚拟滚动
* @default 100
*/
threshold?: number;
/**
* 滚动加载类型，有两种：懒加载和虚拟滚动。<br />值为 `lazy` ，表示滚动时会进行懒加载，非可视区域内的内容将不会默认渲染，直到该内容可见时，才会进行渲染，并且已渲染的内容滚动到不可见时，不会被销毁；<br />值为`virtual`时，表示会进行虚拟滚动，无论滚动条滚动到哪个位置，同一时刻，仅渲染该可视区域内的内容，当需要展示的数据量较大时，建议开启该特性
*/
type: 'lazy' | 'virtual';
}

/**
* @deprecated use TScroll instead
*/
export type InfinityScroll = TScroll;

export interface ScrollToElementParams {
/** 跳转元素下标 */
index?: number;
/** 跳转元素距离顶部的距离 */
top?: number;
/** 单个元素高度非固定场景下，即 isFixedRowHeight = false。延迟设置元素位置，一般用于依赖不同高度异步渲染等场景，单位：毫秒 */
time?: number;
behavior?: 'auto' | 'smooth';
}

export interface ComponentScrollToElementParams extends ScrollToElementParams {
key?: string | number;
}
/**
* 通用全局类型
* */
export type PlainObject = { [key: string]: any };
export type OptionData = {
label?: string;
value?: string | number;
} & PlainObject;
export type TreeOptionData<T = string | number> = {
children?: Array<TreeOptionData<T>> | boolean;
/** option label content */
label?: string | TNode;
/** option search text */
text?: string;
/** option value */
value?: T;
/** option node content */
content?: string | TNode;
} & PlainObject;
export type SizeEnum = 'small' | 'medium' | 'large';
export type ShapeEnum = 'circle' | 'round';
export type HorizontalAlignEnum = 'left' | 'center' | 'right';
export type VerticalAlignEnum = 'top' | 'middle' | 'bottom';
export type LayoutEnum = 'vertical' | 'horizontal';
export type ClassName = { [className: string]: any } | ClassName[] | string;
export type CSSSelector = string;
export interface KeysType {
value?: string;
label?: string;
disabled?: string;
}
export interface TreeKeysType extends KeysType {
children?: string;
}
export interface HTMLElementAttributes {
[attribute: string]: string;
}
export interface TScroll {
/**
* 表示除可视区域外，额外渲染的行数，避免快速滚动过程中，新出现的内容来不及渲染从而出现空白
* @default 20
*/
bufferSize?: number;
/**
* 表示每行内容是否同一个固定高度，仅在 `scroll.type` 为 `virtual` 时有效，该属性设置为 `true` 时，可用于简化虚拟滚动内部计算逻辑，提升性能，此时则需要明确指定 `scroll.rowHeight` 属性的值
* @default false
*/
isFixedRowHeight?: boolean;
/**
* 行高，不会给元素添加样式高度，仅作为滚动时的行高参考。一般情况不需要设置该属性。如果设置，可尽量将该属性设置为每行平均高度，从而使得滚动过程更加平滑
*/
rowHeight?: number;
/**
* 启动虚拟滚动的阈值。为保证组件收益最大化，当数据量小于阈值 `scroll.threshold` 时，无论虚拟滚动的配置是否存在，组件内部都不会开启虚拟滚动
* @default 100
*/
threshold?: number;
/**
* 滚动加载类型，有两种：懒加载和虚拟滚动。<br />值为 `lazy` ，表示滚动时会进行懒加载，非可视区域内的内容将不会默认渲染，直到该内容可见时，才会进行渲染，并且已渲染的内容滚动到不可见时，不会被销毁；<br />值为`virtual`时，表示会进行虚拟滚动，无论滚动条滚动到哪个位置，同一时刻，仅渲染该可视区域内的内容，当需要展示的数据量较大时，建议开启该特性
*/
type: 'lazy' | 'virtual';
}
/**
* @deprecated use TScroll instead
*/
export type InfinityScroll = TScroll;
export interface ScrollToElementParams {
/** 跳转元素下标 */
index?: number;
/** 跳转元素距离顶部的距离 */
top?: number;
/** 单个元素高度非固定场景下，即 isFixedRowHeight = false。延迟设置元素位置，一般用于依赖不同高度异步渲染等场景，单位：毫秒 */
time?: number;
behavior?: 'auto' | 'smooth';
}
export interface ComponentScrollToElementParams extends ScrollToElementParams {
key?: string | number;
}
16 changes: 14 additions & 2 deletions packages/products/tdesign-vue-next/packages/components/popup/popup.en-US.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
:: BASE_DOC ::

## API

### Popup Props

name | type | default | description | required
-- | -- | -- | -- | --
attach | String / Function | 'body' | Typescript：`AttachNode`。[see more ts definition](https://github.com/Tencent/tdesign-vue-next/blob/develop/packages/components/common.ts) | N
closeBtn | Boolean / Slot / Function | - | Typescript：`boolean \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-vue-next/blob/develop/packages/components/common.ts) | N
content | String / Slot / Function | - | Typescript：`string \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-vue-next/blob/develop/packages/components/common.ts) | N
default | String / Slot / Function | - | Typescript：`string \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-vue-next/blob/develop/packages/components/common.ts) | N
delay | Number / Array | - | delay to show or hide popover。Typescript：`number \| Array<number>` | N
Expand All @@ -20,10 +20,12 @@ overlayStyle | Boolean / Object / Function | - | Typescript：`Styles \| ((trigg
placement | String | top | Typescript：`PopupPlacement` `type PopupPlacement = 'top'\|'left'\|'right'\|'bottom'\|'top-left'\|'top-right'\|'bottom-left'\|'bottom-right'\|'left-top'\|'left-bottom'\|'right-top'\|'right-bottom'`。[see more ts definition](https://github.com/Tencent/tdesign-vue-next/blob/develop/packages/components/popup/type.ts) | N
popperOptions | Object | - | popper initial options，details refer to https://popper.js.org/docs | N
showArrow | Boolean | false | \- | N
trigger | String | hover | options：hover/click/focus/mousedown/context-menu | N
trigger | String | hover | options: hover/click/focus/mousedown/context-menu | N
triggerElement | String / Slot / Function | - | Typescript：`string \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-vue-next/blob/develop/packages/components/common.ts) | N
visible | Boolean | - | `v-model` and `v-model:visible` is supported。Typescript：`boolean` | N
defaultVisible | Boolean | - | uncontrolled property。Typescript：`boolean` | N
zIndex | Number | - | \- | N
onOverlayClick | Function | | Typescript：`(context: { e: MouseEvent }) => void`<br/>trigger on popup content click | N
onScroll | Function | | Typescript：`(context: { e: WheelEvent }) => void`<br/> | N
onScrollToBottom | Function | | Typescript：`(context: { e: WheelEvent }) => void`<br/> | N
onVisibleChange | Function | | Typescript：`(visible: boolean, context: PopupVisibleChangeContext) => void`<br/>[see more ts definition](https://github.com/Tencent/tdesign-vue-next/blob/develop/packages/components/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
Expand All @@ -32,6 +34,16 @@ onVisibleChange | Function | | Typescript：`(visible: boolean, context: PopupV

name | params | description
-- | -- | --
overlay-click | `(context: { e: MouseEvent })` | trigger on popup content click
scroll | `(context: { e: WheelEvent })` | \-
scroll-to-bottom | `(context: { e: WheelEvent })` | \-
visible-change | `(visible: boolean, context: PopupVisibleChangeContext)` | [see more ts definition](https://github.com/Tencent/tdesign-vue-next/blob/develop/packages/components/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/>

### PopupInstanceFunctions 组件实例方法

name | params | return | description
-- | -- | -- | --
getOverlay | \- | `HTMLElement` | used to get overly html element
getOverlayState | \- | `{ hover: boolean }` | get mouseover state of overlay
getPopper | \- | `typeof createPopper` | 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 { createPopper } from '@popperjs/core'`<br/>
update | \- | \- | used to update overlay content
18 changes: 15 additions & 3 deletions packages/products/tdesign-vue-next/packages/components/popup/popup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
:: BASE_DOC ::

## 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
closeBtn | Boolean / Slot / Function | - | 是否展示关闭按钮，值为 `true` 显示默认关闭按钮；值为 `false` 则不显示关闭按钮；也可以自定义关闭按钮。TS 类型：`boolean \| TNode`。[通用类型定义](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
Expand All @@ -23,7 +23,9 @@ showArrow | Boolean | false | 是否显示浮层箭头 | N
trigger | String | hover | 触发浮层出现的方式。可选项：hover/click/focus/mousedown/context-menu | N
triggerElement | String / Slot / Function | - | 触发元素。值类型为字符串表示元素选择器。TS 类型：`string \| TNode`。[通用类型定义](https://github.com/Tencent/tdesign-vue-next/blob/develop/packages/components/common.ts) | N
visible | Boolean | - | 是否显示浮层。支持语法糖 `v-model` 或 `v-model:visible`。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-next/blob/develop/packages/components/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
Expand All @@ -32,6 +34,16 @@ 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-next/blob/develop/packages/components/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/>

### PopupInstanceFunctions 组件实例方法

名称 | 参数 | 返回值 | 描述
-- | -- | -- | --
getOverlay | \- | `HTMLElement` | 获取浮层元素
getOverlayState | \- | `{ hover: boolean }` | 获取浮层悬浮状态
getPopper | \- | `typeof createPopper` | 获取当前组件 popper 实例。[详细类型定义](https://github.com/Tencent/tdesign-vue-next/blob/develop/packages/components/popup/type.ts)。<br/>`import { createPopper } from '@popperjs/core'`<br/>
update | \- | \- | 更新浮层内容
8 changes: 3 additions & 5 deletions packages/products/tdesign-vue-next/packages/components/popup/props.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,11 @@ 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'],
},
/** 是否展示关闭按钮，值为 `true` 显示默认关闭按钮；值为 `false` 则不显示关闭按钮；也可以自定义关闭按钮 */
closeBtn: {
type: [Boolean, Function] as PropType<TdPopupProps['closeBtn']>,
},
/** 浮层里面的内容 */
content: {
type: [String, Function] as PropType<TdPopupProps['content']>,
Expand Down Expand Up @@ -90,6 +86,8 @@ export default {
zIndex: {
type: Number,
},
/** 内容面板点击时触发 */
onOverlayClick: Function as PropType<TdPopupProps['onOverlayClick']>,
/** 下拉选项滚动事件 */
onScroll: Function as PropType<TdPopupProps['onScroll']>,
/** 下拉滚动触底事件，常用于滚动到底执行具体业务逻辑 */
Expand Down
31 changes: 26 additions & 5 deletions packages/products/tdesign-vue-next/packages/components/popup/type.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,18 +4,15 @@
* 该文件为脚本自动生成文件，请勿随意修改。如需修改请联系 PMC
* */

import { createPopper } 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;
/**
* 是否展示关闭按钮，值为 `true` 显示默认关闭按钮；值为 `false` 则不显示关闭按钮；也可以自定义关闭按钮
*/
closeBtn?: boolean | TNode;
/**
* 浮层里面的内容
*/
Expand Down Expand Up @@ -97,6 +94,10 @@ export interface TdPopupProps {
* 组件层级，Web 侧样式默认为 5500，移动端和小程序样式默认为 1500
*/
zIndex?: number;
/**
* 内容面板点击时触发
*/
onOverlayClick?: (context: { e: MouseEvent }) => void;
/**
* 下拉选项滚动事件
*/
Expand All @@ -111,6 +112,26 @@ export interface TdPopupProps {
onVisibleChange?: (visible: boolean, context: PopupVisibleChangeContext) => void;
}

/** 组件实例方法 */
export interface PopupInstanceFunctions {
/**
* 获取浮层元素
*/
getOverlay?: () => HTMLElement;
/**
* 获取浮层悬浮状态
*/
getOverlayState?: () => { hover: boolean };
/**
* 获取当前组件 popper 实例
*/
getPopper?: () => typeof createPopper;
/**
* 更新浮层内容
*/
update?: () => void;
}

export type PopupPlacement =
| 'top'
| 'left'
Expand Down
Loading