核心 更新日志

1.6.3 2026-02-27

优化

• 优化对 服务端渲染（SSR） 的支持。

1.6.2 2026-01-19

特性

• createPopupPlus() 函数的 zIndex 选项现在支持传入一个工厂函数，每次渲染弹出层时，会调用该函数获取一个新的 z-index 值。

1.6.1 2026-01-16

优化

• 优化底层渲染逻辑，从而为更多非组件环境提供渲染支持，提升兼容性。
• 优化性能，当使用 PopupRoot 根组件时，所有获取控制器的方法都将返回缓存中共享的无状态控制器实例，极大减少内存消耗。

1.6.0 2026-01-15

重大改动

TIP

从 1.6.0 版本开始，Vue Popup Plus 的核心实例和控制器实例拆分，核心实例仅负责插件的安装，而控制器实例则负责弹出层的创建和管理。

对于插件使用者，需要将原有的 createPopup() 函数替换为 createPopupPlus() 函数。

对于插件开发者，需要注意的是 definePlugin() 函数的 install() 方法，第一个参数 popup 控制器实例将不再提供，取而代之的是 config 参数，新的 config 参数包含了原有的 customProperties 、 customAnimations 等配置项。

特性

• 新增 createPopupPlus() 函数，用于创建核心实例。
• createPopupPlus() 函数新增 logFilter 参数，用于自定义日志过滤函数，默认为 undefined。
• 新增 usePopupInstanceId() 组合式工具函数，用于在弹出层所渲染的 所有子代组件 中获取当前的弹出层实例ID。
• 新增 usePopupComputedStyle() 组合式工具函数，用于获取当前弹出层的视图组件的计算样式。
• render() 函数新增 maskTransparent 参数，用于设置是否启用透明遮罩层，默认值为 false 。
• render() 函数新增 maskDestroy 参数，用于设置遮罩层点击是否可以销毁弹出层，可传入一个函数，该函数接收一个 (payload?: any) => Promise<void> 类型的函数作为参数，执行后将销毁弹出层，可传入销毁携带的负载参数，返回的 Promise 对象会在弹出层销毁动画完成后 resolve() 。
• usePopup() 函数现在将会自动在组件内获取组件的 上下文 ，从而提供对其他框架更好的兼容性，如果你仅在组件内使用 usePopup() 函数，那么 PopupRoot 根组件将并不再是必须的。

优化

• 优化遮罩层在 dark 主题下的显示效果。

修复

• 修复 popup.destroy() 函数返回值类型应该为 Promise<void> 但实际返回值类型为 void 的bug。

破坏性改动

DANGER

• createPopup() 函数现在已经被移除，其原有功能已经被 createPopupPlus() 和 usePopup() 函数所替代。
• definePlugin() 定义弹出层插件函数的 install() 方法移除第一个参数 controller ，因为现在控制器不会提前生成，而是在调用 usePopup() 时才会生成。 弹出层插件开发者无法直接访问弹出层控制器实例，只能通过第二个参数 config 的 customProperties 属性对弹出层控制器进行扩展方法时，通过 this 访问弹出层控制器实例。
• render() 函数移除 maskClickClose 参数，可使用功能更强大的 maskDestroy 参数代替。

1.5.2 2025-12-23

修复

• 修复导出版本号与实际版本号不同步的问题

1.5.1 2025-12-23

修复

• 修复依赖引入的问题

1.5.0 2025-12-23

特性

• 新增 PopupRoot 组件，用于同步应用上下文，彻底解决独立渲染弹出层无法共享应用上下文的问题。
• render() 函数新增 placement 参数，默认居中 center ，用于指定弹出层的位置。
• createPopup() 函数新增 logHandler 参数，用于自定义日志打印函数。
• 调试模式自动开启详细日志输出，方便开发者调试。
• use() 插件注册函数开启风险校验，针对未定义作者 author 参数的插件将会在调试模式下打印警告日志，提示开发者注意插件风险。
• use() 插件注册函数开启对核心版本的校验，针对校验失败的插件将会在调试模式下打印错误日志，并且阻止该插件的注册。
• 新增导出 Log 、 LogType 、 printLog 等工具 API ，用于插件开发者提供插件日志输出。
• 新增导出 LogGroupItemType 、 LogGroupItem 等工具类型，用于插件开发者提供插件日志分组输出。
• 新增导出 Version 类型，用于插件开发者使用该类型进行版本适配和维护。
• 新增导出 TypeScript 工具类型 ExtractComponentPropTypes<T>，用于从组件类型中提取属性类型。

优化

• render() 函数的 componentProps 参数支持自动推导视图组件的属性类型，提供更好的开发体验。
• 优化遮罩层在不同主题下的渲染效果。
• 移除冗余代码和依赖。

1.4.0 2025-11-20

特性

• definePlugin 方法支持自定义插件 注册选项，会自动在调用 use() 函数注册插件时提供对应的参数选项类型推断，为插件使用者提供更好的使用体验。

优化

• 提供更完整的类型定义，提升开发体验。
• 提供更详细的代码注释，方便开发者理解和使用。

1.3.4 2025-11-08

修复

• 修复 debugMode 模式下无法正常销毁弹出层根节点的问题。
• 修复渲染选项 maxWidth 和 maxHeight 无法正确生效的问题。

1.3.3 2025-11-08

优化

• 优化遮罩层的渲染效果。

1.3.2 2025-11-07

优化

• 优化弹出层在亮色主题下，遮罩层的渲染效果。

1.3.1 2025-11-07

修复

• 修复渲染选项 viewAnimation 偶现无法正确触发动画的问题。

1.3.0 2025-11-05

特性

• 支持暗色主题。
• 遮罩层支持高斯模糊，默认开启，提供配置项 maskBlur 用于关闭高斯模糊。
• 支持每个弹出层独立设置禁用滚动条

破坏性改动

DANGER

• 优化部分渲染选项名称。

1.2.1 2025-10-31

特性

• 插件创建选项支持 debugMode 模式，开启后会在Vue devtools 中显示弹出层组件信息，方便开发调试。

性能提升

• 优化弹出层的渲染性能，默认使用 VNode 渲染，仅在 debugMode 模式下使用独立 app 实例渲染，方便调试。

1.2.0 2025-10-29

特性

• 新增插件创建选项 autoDisableScroll ，用于自动禁用滚动条。

适配

• 适配 vue 3.5.22 版本，提供更好的兼容性和性能。

修复

• 修复类型导出问题，确保在使用时能够正确获取到类型定义。

1.1.5 2025-10-28

修复

• 修复类型导出问题，确保在使用时能够正确获取到类型定义。

1.1.4 2025-10-28

修复

• 修复类型导出问题，确保在使用时能够正确获取到类型定义。

1.1.3 2025-10-28

修复

• 修复类型导出问题，确保在使用时能够正确获取到类型定义。

1.1.2 2025-10-28

修复

• 修复核心的控制器默认挂载 Vue 实例的类型声明问题，提供完善的类型定义。

1.1.1 2025-10-28

修复

• 修复类型导出问题，确保在使用时能够正确获取到类型定义。

1.1.0 2025-10-27

特性

• 新增控制器实例 render() 函数的渲染选项 viewTranslateX 、 viewTranslateY ，用于控制弹出层的位移。
• 新增控制器实例 update() 函数，用于更新弹出层的渲染选项。

代码重构

• 重构插件系统，提供更高的可扩展性。
• 重构动画系统，提升流畅度，提供更多配置项。

1.0.0 2025-10-27

特性

• 从 vue-popup 成功迁移到 vue 3 版本