做后台管理系统做得多了弹窗几乎是无处不在的组件。我最早图省事直接在业务页面里用一个v-if控制的全屏遮罩内层再放一张白底卡片。单页面跑起来还挺顺畅直到某天产品说“弹窗里要再嵌一个弹窗”然后页面上又出现按钮 loading 盖不住弹窗、某些容器设了transform后 fixed 定位完全失灵的问题我才意识到这类通用组件必须单独抽出来而且要用 TypeScript 从一开始把类型边界定清楚。这篇博客就讲我用 TypeScript 编写 Vue 3 Modal 组件的完整过程重点包括teleport容器管理的新思路以及如何把 Loading 组件的宿主节点插入与销毁整个收敛到组件自身。如果你是刚接触 Vue 3 TypeScript或者正在维护一套后台管理系统的前端可以直接照着这套思路落地。1. 为什么我坚持用 TypeScript 写这个 Modal1.1 从一版只跑得通、但不敢维护的 JS 弹窗说起以前写过一版纯 JS 的全局弹窗功能是能跑但维护成本高得吓人。问题集中在几处组件的 props 没有约定业务里传visible的有传show的也有回调事件经常拼错onClose和close在不同页面里各写各的更麻烦的是组件内部直接修改 propsVue 的单项数据流被打破后多个弹窗互相影响查了半天都找不到是谁改了状态。那时候我才意识到弹窗这种被几十个页面复用的组件最需要的不是功能多炫而是“边界稳定”。TypeScript 恰好能解决这个问题把 props 写成 interface所有调用点都只能按照定义好的结构传参把 emits 写成类型化的方法签名事件名拼错了在编译期就报错。对于 Modal 这种“谁都会用到、谁都能改出 bug”的组件类型约束带来的收益远大于写类型的那点成本。1.2 用 interface 把弹窗的参数边界一次定死我在项目里先建立了一份types/modal.ts专门放 Modal 相关的类型定义。核心结构是这样的export interface ModalProps { modelValue: boolean title?: string width?: number | string closeOnClickOverlay?: boolean closeOnPressEscape?: boolean lockScroll?: boolean appendTo?: string | HTMLElement zIndex?: number } export interface ModalEmits { (e: update:modelValue, value: boolean): void (e: open): void (e: close): void (e: closed): void }这里有个关键取舍为什么用modelValue而不是visible因为v-model是 Vue 组件之间最通用的契约用modelValue可以保证任何上层封装组件表单弹窗、确认框、图片预览在使用时行为一致。类型定义里用了函数重载的写法来声明 emits这样在父组件监听close事件时编辑器能直接把参数类型提示出来。当我要扩展一个ConfirmModal时interface 继承的好处就非常明显了export interface ConfirmModalProps extends ModalProps { content: string confirmText?: string cancelText?: string }继承之后新组件天然拥有基础弹窗的全部能力同时又不需要把原有类型重新写一遍。这比复制粘贴十几行 props 清爽多了。1.3 让 defineProps 的类型推导和运行时校验各司其职Vue 3 的script setup提供了defineProps的泛型写法这是 TypeScript 集成中比较顺手的一处设计。直接用泛型声明script setup langts const props withDefaults(definePropsModalProps(), { width: 520, closeOnClickOverlay: true, closeOnPressEscape: true, lockScroll: true, }) /scriptwithDefaults给可选属性提供默认值类型推导依然完整。只有一点要注意泛型写法状态下运行时 prop 校验就不能做了。如果你需要校验传进来的title必须是非空字符串那就只能回到运行时定义defineProps({ title: { type: String, required: true, }, })但这会失去 interface 的统一约束。我的建议是二选一而且优先用泛型写法把校验逻辑放到业务调用方。因为 Modal 这种组件props 类型写清楚已经能挡住大多数误用运行时校验反而增加了双重维护成本。2. Teleport 到底解决了什么问题以及挂到 body 后真正难缠的坑2.1 被 overflow 和 transform 卡住的弹层们Modal 最核心的问题不是样式多好看而是“怎么从父容器里逃出去”。假设弹窗被放在一个overflow: hidden的容器里高度一旦超出就被裁掉放在overflow: auto容器里弹窗会跟着父容器一起滚动。更隐蔽的是如果祖先元素设置了transform它就会成为 fixed 定位元素的包含块弹窗原本想钉在视口中间结果变成了钉在某个 div 的相对坐标上。用过position: fixed的同学应该都被这种问题坑过。Vue 3 的Teleport就是为此设计的。它能把组件内部的 DOM 直接传送到指定的目标位置语法很直接Teleport tobody div v-ifvisible classmodal/div /Teleport渲染之后.modal的 DOM 节点出现在body末尾父容器的overflow和transform都管不到它了。你可以把它理解成一个“传送门”内部的结构逻辑、状态传递仍然属于当前子组件但 DOM 产出已经换了一个真正的宿主位置。2.2 挂到 body 不等于万事大吉把弹窗挂到 body 之后只是解决了“被裁剪”的问题紧接着会撞上一个新问题层叠上下文。body 下同时存在多个组件产生的浮层时谁后插入谁就可能盖上另一个。如果项目里同时用了 Element Plus、TDesign、自己的组件库各种弹层插件各自管理各自的z-index自研 Modal 很容易被别人的抽屉或消息提示盖住。只靠Teleport tobody解决不了层级问题需要自己维护一个全局的z-index分配策略。我在项目里的做法是维护一个弹窗栈每次打开弹窗时从当前应用的最大值往上递增let modalStack: string[] [] let maxZIndex 3000 export function openModal(id: string): number { modalStack.push(id) maxZIndex 10 return maxZIndex } export function closeModal(id: string): void { modalStack modalStack.filter((item) item ! id) }这样弹窗每打开一个层级就比上一个高一点基本能保证后弹出来的窗口始终在最上层。另外如果你是做 SSR 项目tobody在服务端会直接报错因为服务端没有document.body所有 DOM 操作都得放到客户端生命周期里执行或者用disabled属性在 SSR 阶段先降级为原位渲染。3. Teleport 容器管理的新思路让宿主节点跟随组件生灭3.1 不在 index.html 里写死挂载点很多教程教你在index.html里手动加一个div idmodal-root然后所有弹窗统一Teleport to#modal-root。这个方案能用但我不太推荐。原因有几个一是挂载点在页面入口阶段就已经存在如果弹窗组件在应用初始化之前被意外调用会出现“宿主节点不存在但弹窗已经打开”的错乱二是多团队协作时谁都可以往这个固定节点里塞东西节点被第三方库清空或重复建节点的事很容易发生。我的做法是宿主节点由工具函数动态创建项目里根本没有写死的弹窗容器。核心代码就一段引用计数管理let sharedHost: HTMLElement | null null let hostRefCount 0 export function acquireHost(): HTMLElement { if (!sharedHost) { sharedHost document.createElement(div) sharedHost.setAttribute(data-role, modal-host) document.body.appendChild(sharedHost) } hostRefCount 1 return sharedHost } export function releaseHost(): void { hostRefCount - 1 if (hostRefCount 0 sharedHost) { sharedHost.remove() sharedHost null } }每个 Modal 组件在onMounted时调用acquireHost获取容器在onBeforeUnmount时调用releaseHost。第一个弹窗打开时创建容器最后一个弹窗关闭时容器自动销毁整个过程应用主入口不用做任何额外配置。关键点是引用计数因为多个弹窗可能同时存在如果每个组件卸载时都把容器删掉其他正在展示的弹窗就会全部失效。3.2 多个 Modal 实例共享容器时的挂载顺序容器是共享的但弹窗的显示顺序不能乱。Teleport会把所有弹窗内容依次追加到容器末尾理论上先打开的 Modal 在 DOM 里位置靠前后打开的在后面靠后天然满足层叠顺序。但实际项目里会出现异步组件、动态 import、延迟渲染等情况组件挂载顺序和用户点击顺序不一定一致。解决方案简单可靠用组件的 uid 作为唯一标识打开弹窗时记录 uid渲染时给每个弹窗绑定一个根据打开顺序生成的zIndex。我通常在Modal.vue里这样处理const instance getCurrentInstance() const uid instance?.uid?.toString() ?? Math.random().toString(36) let currentZIndex 0 onMounted(() { currentZIndex openModal(uid) })打开时分配层级关闭时从栈中移除。只要所有弹窗组件都用同一套openModal/closeModal工具层级就不会互相冲突。这个方案比单纯靠appendChild顺序可靠因为即使一个弹窗因为动画还没结束而延迟销毁新弹窗依然能拿到更高的层级。3.3 动画结束前不要释放宿主节点这个坑是在写过渡动画时踩到的。刚开始我把releaseHost放在onBeforeUnmount里结果弹窗的离场动画刚播放到一半共享容器直接被移出了 DOM动画瞬间中断。原因是Teleport的内容一旦被卸载它的宿主节点即使还在 body 下内容也已经不复存在。正确做法是等Transition的after-leave事件触发后再释放容器。如果是命令式关闭弹窗要把关闭动作设计成“先开始离场动画动画结束后再真正清理组件状态”。这样弹窗在视觉上是流畅地淡出DOM 清理也安全。这也是我在文章最后会再强调的一点弹窗组件的生命周期管理和普通业务组件有本质区别它同时受到渲染层、动画层、DOM 宿主层三方的牵制。4. Loading 组件把插入与销毁逻辑收进组件自身4.1 传统命令式 Loading 的清理噩梦Modal 组件还好业务方只需要v-model控制开关Loading 组件则是另一个难啃的骨头。大部分项目里的 Loading 是命令式调用的比如const container document.createElement(div) const instance createApp({ template: div classloading加载中.../div, }).mount(container) document.body.appendChild(container) // 倒计时结束后 container.remove() instance.unmount()这段代码到处散落着一个隐患忘记清理。很多人只做了document.body.appendChild却忘了container.remove或者只卸载了 Vue 应用实例但遗留了空节点。一次两次还好后台管理系统里按钮被反复点击每个请求都触发一次 Loading没几轮页面上就挂满了残留的占位 div。更麻烦的是异步请求报错时如果finally里忘了closeLoading 会永远盖在页面上用户只能整个刷新。4.2 核心设计组件自己负责最后清理调用方只负责开关我后来把 Loading 的插入和销毁逻辑重构了调用方只需要拿到一个controller对象调用close()就能完成收尾所有 DOM 清理动作都在组件内部自己的生命周期里执行。整体思路分三步。第一步定义一个独立的 Loading 面板组件组件内部接收一个可选容器引用并且在卸载时自己删除容器script setup langts import { onBeforeUnmount, withDefaults } from vue interface LoadingViewProps { text?: string container?: HTMLElement } const props withDefaults(definePropsLoadingViewProps(), { text: 加载中..., }) onBeforeUnmount(() { if (props.container props.container.parentNode) { props.container.parentNode.removeChild(props.container) } }) /script template div classloading-mask div classloading-spinner/div p{{ text }}/p /div /template第二步在工具函数里动态创建容器并通过render渲染组件实例。这样省去了createApp的额外应用实例开销性能更好import { createVNode, render } from vue import type { VNode } from vue import LoadingView from ./LoadingView.vue export interface LoadingController { close: () void } export function openLoading(options: { text?: string } {}): LoadingController { const container document.createElement(div) document.body.appendChild(container) let vnode: VNode createVNode(LoadingView, { text: options.text, container, }) render(vnode, container) return { close() { render(null, container) }, } }第三步调用方在使用时就只管调用和关闭不需要再碰任何 DOMconst loading openLoading({ text: 正在保存... }) try { await saveForm(data) } finally { loading.close() }当close()被调用时render(null, container)会触发 Loading 面板组件的卸载流程组件自身的onBeforeUnmount钩子再把容器从 body 里移除。这样“插入动作”由工具函数完成“销毁动作”收敛到了组件自身业务方永远不可能遗漏清理逻辑。如果finally忘记了或者中途抛了异常只要调用方在正确作用域里执行close残留问题就永远不会发生。4.3 为什么用 render 而不是 createApp以及 appContext 的坑这里要展开说一下为什么我用render而不是createApp。createApp的本质是创建一个独立的 Vue 应用实例它和当前页面的组件树不在同一个上下文里。带来的直接后果是组件内使用provide/inject拿不到根组件注入的数据全局注册的组件和指令也不会在你动态渲染的 Loading vnode 里生效。如果你的组件有全局自定义指令Loading 面板里就失效排查起来会非常迷惑。解决办法是手动把当前组件实例的appContext传过去。在需要打开 Loading 的地方比如某个页面组件的setup里用getCurrentInstance()获取上下文然后传给 vnodeimport { getCurrentInstance } from vue export function useLoadingInCurrentComponent() { const instance getCurrentInstance() const open (options: { text?: string } {}) { const container document.createElement(div) document.body.appendChild(container) const vnode createVNode(LoadingView, { ...options, container, }) vnode.appContext instance?.appContext ?? null render(vnode, container) return { close: () render(null, container), } } return { open } }这样做之后动态渲染的 Loading 组件能拿到全局组件、指令、插件注册表现和写在模板里完全一致。这个细节在常规文档里很少提到但实际项目中遇到一次就能记一辈子。5. Transition、层级与无障碍自研弹窗容易忽略的三个细节5.1 Transition 必须套在 Teleport 内部且动画完成前不能释放宿主弹窗打开和关闭通常要有动画。Teleport 只是调整 DOM 位置它本身不做过渡动画所以最终结构应该是 Teleport 包裹 Transition 再包裹内容节点Teleport :tohost Transition namemodal-fade after-leavehandleAfterLeave div v-ifvisible classmodal-mask div classmodal-container slot / /div /div /Transition /Teleportafter-leave是关闭动画真正结束的时刻。前面说过宿主节点必须在这个钩子里才做释放否则动画会被瞬间截断。我遇到的另一个细节是如果v-if一开始就是false打开时想要出现动画需要在 Transition 上加上appear属性否则首次渲染会直接显示没有过渡效果。5.2 打开弹窗时锁滚动关闭时必须还原之前的滚动状态Modal 打开后用户应该不能滚动背景页面。最直观的做法是设置document.body.style.overflow hidden。但这样直接把原本的overflow值覆盖掉了如果用户页面上存在内联overflow: auto关闭弹窗时恢复就会出错。更稳妥的做法是保存旧值再还原function lockScroll() { const body document.body const oldOverflow body.style.overflow body.dataset.prevOverflow oldOverflow body.style.overflow hidden } function unlockScroll() { const body document.body const prev body.dataset.prevOverflow ?? body.style.overflow prev delete body.dataset.prevOverflow }多弹窗场景还要带引用计数第一个弹窗打开时锁滚动最后一个弹窗关闭时恢复滚动。中间层级的弹窗关闭不能贸然解锁否则底层弹窗还开着背景页面却已经可以滚动了。5.3 无障碍和焦点管理至少要把这三件事做对自研弹窗如果不做无障碍处理视觉上没问题但键盘用户和读屏软件用户的使用体验会很差。最基本的三件事在弹窗容器上加上roledialog和aria-modaltrue告诉辅助技术这是一个模态对话框。弹窗打开时记录当前聚焦的元素关闭后还原焦点。否则关闭后焦点会跑回到 body用户键盘操作就会乱掉。监听Escape键关闭弹窗这是桌面端用户非常习惯的操作。简单的焦点还原实现是这样的let lastFocus: HTMLElement | null null onMounted(() { lastFocus document.activeElement as HTMLElement | null }) onBeforeUnmount(() { lastFocus?.focus() })如果弹窗内有关闭按钮最好打开后默认聚焦关闭按钮让键盘用户能直接走 Tab 循环。完整实现 focus trap 还需要拦截 Tab 键把焦点限制在弹窗内部逻辑稍微复杂但不难理解。我通常先在基本焦点还原的基础上跑通功能再根据产品需要决定加不加完整 focus trap避免一上来就把组件复杂度顶上去。6. 顺带说说如何给 Modal 组件补充全局类型声明TypeScript 项目里如果 Modal 组件通过app.component(BaseModal)全局注册模板里直接用却没有类型提示会让前面的类型工作打折扣。解决办法是在项目的types/目录下补充全局组件声明。这也是网上问得比较多的问题types 文件夹里的声明文件到底怎么写。以我的组件库为例在src/types/global-components.d.ts里写import type { ModalProps } from ./modal declare module vue { export interface GlobalComponents { BaseModal: { props: ModalProps emits: { (e: update:modelValue, value: boolean): void (e: open): void (e: close): void (e: closed): void } } } } export {}有了这段声明任何组件文件里直接用BaseModal v-modelshow /都能拿到完整的 props 和事件提示。配合前面定义的ModalProps整个组件体系从业务调用到内部实现全部处于类型约束之下后续同事接手也能很快找到所有字段定义的位置。实际项目中我还把ModalProps、ConfirmModalProps、LoadingController这些类型集中在types/modal.ts和types/loading.ts全局声明文件只负责映射到组件。这样比把所有类型堆在一个.d.ts里更清晰维护起来也方便。热词里经常看到“TypeScript types 文件夹的声明文件如何使用”这类问题本质就是理解.d.ts只做类型声明不产出运行时代码把类型定义和运行逻辑分开项目结构就清楚很多。至少在我自己项目里这套做法已经跑了两个完整业务周期弹窗相关的 bug 比原来少了大半。Modal 和 Loading 的代码量本身不大但要把 teleport 的容器管理、组件的自动化清理、动画时序和类型约束都安排明白还是需要沉下心来把每个环节的边界想清楚。希望这篇分享能把最关键的几条经验给你带到。
做后台管理系统做得多了弹窗几乎是无处不在的组件。我最早图省事直接在业务页面里用一个v-if控制的全屏遮罩内层再放一张白底卡片。单页面跑起来还挺顺畅直到某天产品说“弹窗里要再嵌一个弹窗”然后页面上又出现按钮 loading 盖不住弹窗、某些容器设了transform后 fixed 定位完全失灵的问题我才意识到这类通用组件必须单独抽出来而且要用 TypeScript 从一开始把类型边界定清楚。这篇博客就讲我用 TypeScript 编写 Vue 3 Modal 组件的完整过程重点包括teleport容器管理的新思路以及如何把 Loading 组件的宿主节点插入与销毁整个收敛到组件自身。如果你是刚接触 Vue 3 TypeScript或者正在维护一套后台管理系统的前端可以直接照着这套思路落地。1. 为什么我坚持用 TypeScript 写这个 Modal1.1 从一版只跑得通、但不敢维护的 JS 弹窗说起以前写过一版纯 JS 的全局弹窗功能是能跑但维护成本高得吓人。问题集中在几处组件的 props 没有约定业务里传visible的有传show的也有回调事件经常拼错onClose和close在不同页面里各写各的更麻烦的是组件内部直接修改 propsVue 的单项数据流被打破后多个弹窗互相影响查了半天都找不到是谁改了状态。那时候我才意识到弹窗这种被几十个页面复用的组件最需要的不是功能多炫而是“边界稳定”。TypeScript 恰好能解决这个问题把 props 写成 interface所有调用点都只能按照定义好的结构传参把 emits 写成类型化的方法签名事件名拼错了在编译期就报错。对于 Modal 这种“谁都会用到、谁都能改出 bug”的组件类型约束带来的收益远大于写类型的那点成本。1.2 用 interface 把弹窗的参数边界一次定死我在项目里先建立了一份types/modal.ts专门放 Modal 相关的类型定义。核心结构是这样的export interface ModalProps { modelValue: boolean title?: string width?: number | string closeOnClickOverlay?: boolean closeOnPressEscape?: boolean lockScroll?: boolean appendTo?: string | HTMLElement zIndex?: number } export interface ModalEmits { (e: update:modelValue, value: boolean): void (e: open): void (e: close): void (e: closed): void }这里有个关键取舍为什么用modelValue而不是visible因为v-model是 Vue 组件之间最通用的契约用modelValue可以保证任何上层封装组件表单弹窗、确认框、图片预览在使用时行为一致。类型定义里用了函数重载的写法来声明 emits这样在父组件监听close事件时编辑器能直接把参数类型提示出来。当我要扩展一个ConfirmModal时interface 继承的好处就非常明显了export interface ConfirmModalProps extends ModalProps { content: string confirmText?: string cancelText?: string }继承之后新组件天然拥有基础弹窗的全部能力同时又不需要把原有类型重新写一遍。这比复制粘贴十几行 props 清爽多了。1.3 让 defineProps 的类型推导和运行时校验各司其职Vue 3 的script setup提供了defineProps的泛型写法这是 TypeScript 集成中比较顺手的一处设计。直接用泛型声明script setup langts const props withDefaults(definePropsModalProps(), { width: 520, closeOnClickOverlay: true, closeOnPressEscape: true, lockScroll: true, }) /scriptwithDefaults给可选属性提供默认值类型推导依然完整。只有一点要注意泛型写法状态下运行时 prop 校验就不能做了。如果你需要校验传进来的title必须是非空字符串那就只能回到运行时定义defineProps({ title: { type: String, required: true, }, })但这会失去 interface 的统一约束。我的建议是二选一而且优先用泛型写法把校验逻辑放到业务调用方。因为 Modal 这种组件props 类型写清楚已经能挡住大多数误用运行时校验反而增加了双重维护成本。2. Teleport 到底解决了什么问题以及挂到 body 后真正难缠的坑2.1 被 overflow 和 transform 卡住的弹层们Modal 最核心的问题不是样式多好看而是“怎么从父容器里逃出去”。假设弹窗被放在一个overflow: hidden的容器里高度一旦超出就被裁掉放在overflow: auto容器里弹窗会跟着父容器一起滚动。更隐蔽的是如果祖先元素设置了transform它就会成为 fixed 定位元素的包含块弹窗原本想钉在视口中间结果变成了钉在某个 div 的相对坐标上。用过position: fixed的同学应该都被这种问题坑过。Vue 3 的Teleport就是为此设计的。它能把组件内部的 DOM 直接传送到指定的目标位置语法很直接Teleport tobody div v-ifvisible classmodal/div /Teleport渲染之后.modal的 DOM 节点出现在body末尾父容器的overflow和transform都管不到它了。你可以把它理解成一个“传送门”内部的结构逻辑、状态传递仍然属于当前子组件但 DOM 产出已经换了一个真正的宿主位置。2.2 挂到 body 不等于万事大吉把弹窗挂到 body 之后只是解决了“被裁剪”的问题紧接着会撞上一个新问题层叠上下文。body 下同时存在多个组件产生的浮层时谁后插入谁就可能盖上另一个。如果项目里同时用了 Element Plus、TDesign、自己的组件库各种弹层插件各自管理各自的z-index自研 Modal 很容易被别人的抽屉或消息提示盖住。只靠Teleport tobody解决不了层级问题需要自己维护一个全局的z-index分配策略。我在项目里的做法是维护一个弹窗栈每次打开弹窗时从当前应用的最大值往上递增let modalStack: string[] [] let maxZIndex 3000 export function openModal(id: string): number { modalStack.push(id) maxZIndex 10 return maxZIndex } export function closeModal(id: string): void { modalStack modalStack.filter((item) item ! id) }这样弹窗每打开一个层级就比上一个高一点基本能保证后弹出来的窗口始终在最上层。另外如果你是做 SSR 项目tobody在服务端会直接报错因为服务端没有document.body所有 DOM 操作都得放到客户端生命周期里执行或者用disabled属性在 SSR 阶段先降级为原位渲染。3. Teleport 容器管理的新思路让宿主节点跟随组件生灭3.1 不在 index.html 里写死挂载点很多教程教你在index.html里手动加一个div idmodal-root然后所有弹窗统一Teleport to#modal-root。这个方案能用但我不太推荐。原因有几个一是挂载点在页面入口阶段就已经存在如果弹窗组件在应用初始化之前被意外调用会出现“宿主节点不存在但弹窗已经打开”的错乱二是多团队协作时谁都可以往这个固定节点里塞东西节点被第三方库清空或重复建节点的事很容易发生。我的做法是宿主节点由工具函数动态创建项目里根本没有写死的弹窗容器。核心代码就一段引用计数管理let sharedHost: HTMLElement | null null let hostRefCount 0 export function acquireHost(): HTMLElement { if (!sharedHost) { sharedHost document.createElement(div) sharedHost.setAttribute(data-role, modal-host) document.body.appendChild(sharedHost) } hostRefCount 1 return sharedHost } export function releaseHost(): void { hostRefCount - 1 if (hostRefCount 0 sharedHost) { sharedHost.remove() sharedHost null } }每个 Modal 组件在onMounted时调用acquireHost获取容器在onBeforeUnmount时调用releaseHost。第一个弹窗打开时创建容器最后一个弹窗关闭时容器自动销毁整个过程应用主入口不用做任何额外配置。关键点是引用计数因为多个弹窗可能同时存在如果每个组件卸载时都把容器删掉其他正在展示的弹窗就会全部失效。3.2 多个 Modal 实例共享容器时的挂载顺序容器是共享的但弹窗的显示顺序不能乱。Teleport会把所有弹窗内容依次追加到容器末尾理论上先打开的 Modal 在 DOM 里位置靠前后打开的在后面靠后天然满足层叠顺序。但实际项目里会出现异步组件、动态 import、延迟渲染等情况组件挂载顺序和用户点击顺序不一定一致。解决方案简单可靠用组件的 uid 作为唯一标识打开弹窗时记录 uid渲染时给每个弹窗绑定一个根据打开顺序生成的zIndex。我通常在Modal.vue里这样处理const instance getCurrentInstance() const uid instance?.uid?.toString() ?? Math.random().toString(36) let currentZIndex 0 onMounted(() { currentZIndex openModal(uid) })打开时分配层级关闭时从栈中移除。只要所有弹窗组件都用同一套openModal/closeModal工具层级就不会互相冲突。这个方案比单纯靠appendChild顺序可靠因为即使一个弹窗因为动画还没结束而延迟销毁新弹窗依然能拿到更高的层级。3.3 动画结束前不要释放宿主节点这个坑是在写过渡动画时踩到的。刚开始我把releaseHost放在onBeforeUnmount里结果弹窗的离场动画刚播放到一半共享容器直接被移出了 DOM动画瞬间中断。原因是Teleport的内容一旦被卸载它的宿主节点即使还在 body 下内容也已经不复存在。正确做法是等Transition的after-leave事件触发后再释放容器。如果是命令式关闭弹窗要把关闭动作设计成“先开始离场动画动画结束后再真正清理组件状态”。这样弹窗在视觉上是流畅地淡出DOM 清理也安全。这也是我在文章最后会再强调的一点弹窗组件的生命周期管理和普通业务组件有本质区别它同时受到渲染层、动画层、DOM 宿主层三方的牵制。4. Loading 组件把插入与销毁逻辑收进组件自身4.1 传统命令式 Loading 的清理噩梦Modal 组件还好业务方只需要v-model控制开关Loading 组件则是另一个难啃的骨头。大部分项目里的 Loading 是命令式调用的比如const container document.createElement(div) const instance createApp({ template: div classloading加载中.../div, }).mount(container) document.body.appendChild(container) // 倒计时结束后 container.remove() instance.unmount()这段代码到处散落着一个隐患忘记清理。很多人只做了document.body.appendChild却忘了container.remove或者只卸载了 Vue 应用实例但遗留了空节点。一次两次还好后台管理系统里按钮被反复点击每个请求都触发一次 Loading没几轮页面上就挂满了残留的占位 div。更麻烦的是异步请求报错时如果finally里忘了closeLoading 会永远盖在页面上用户只能整个刷新。4.2 核心设计组件自己负责最后清理调用方只负责开关我后来把 Loading 的插入和销毁逻辑重构了调用方只需要拿到一个controller对象调用close()就能完成收尾所有 DOM 清理动作都在组件内部自己的生命周期里执行。整体思路分三步。第一步定义一个独立的 Loading 面板组件组件内部接收一个可选容器引用并且在卸载时自己删除容器script setup langts import { onBeforeUnmount, withDefaults } from vue interface LoadingViewProps { text?: string container?: HTMLElement } const props withDefaults(definePropsLoadingViewProps(), { text: 加载中..., }) onBeforeUnmount(() { if (props.container props.container.parentNode) { props.container.parentNode.removeChild(props.container) } }) /script template div classloading-mask div classloading-spinner/div p{{ text }}/p /div /template第二步在工具函数里动态创建容器并通过render渲染组件实例。这样省去了createApp的额外应用实例开销性能更好import { createVNode, render } from vue import type { VNode } from vue import LoadingView from ./LoadingView.vue export interface LoadingController { close: () void } export function openLoading(options: { text?: string } {}): LoadingController { const container document.createElement(div) document.body.appendChild(container) let vnode: VNode createVNode(LoadingView, { text: options.text, container, }) render(vnode, container) return { close() { render(null, container) }, } }第三步调用方在使用时就只管调用和关闭不需要再碰任何 DOMconst loading openLoading({ text: 正在保存... }) try { await saveForm(data) } finally { loading.close() }当close()被调用时render(null, container)会触发 Loading 面板组件的卸载流程组件自身的onBeforeUnmount钩子再把容器从 body 里移除。这样“插入动作”由工具函数完成“销毁动作”收敛到了组件自身业务方永远不可能遗漏清理逻辑。如果finally忘记了或者中途抛了异常只要调用方在正确作用域里执行close残留问题就永远不会发生。4.3 为什么用 render 而不是 createApp以及 appContext 的坑这里要展开说一下为什么我用render而不是createApp。createApp的本质是创建一个独立的 Vue 应用实例它和当前页面的组件树不在同一个上下文里。带来的直接后果是组件内使用provide/inject拿不到根组件注入的数据全局注册的组件和指令也不会在你动态渲染的 Loading vnode 里生效。如果你的组件有全局自定义指令Loading 面板里就失效排查起来会非常迷惑。解决办法是手动把当前组件实例的appContext传过去。在需要打开 Loading 的地方比如某个页面组件的setup里用getCurrentInstance()获取上下文然后传给 vnodeimport { getCurrentInstance } from vue export function useLoadingInCurrentComponent() { const instance getCurrentInstance() const open (options: { text?: string } {}) { const container document.createElement(div) document.body.appendChild(container) const vnode createVNode(LoadingView, { ...options, container, }) vnode.appContext instance?.appContext ?? null render(vnode, container) return { close: () render(null, container), } } return { open } }这样做之后动态渲染的 Loading 组件能拿到全局组件、指令、插件注册表现和写在模板里完全一致。这个细节在常规文档里很少提到但实际项目中遇到一次就能记一辈子。5. Transition、层级与无障碍自研弹窗容易忽略的三个细节5.1 Transition 必须套在 Teleport 内部且动画完成前不能释放宿主弹窗打开和关闭通常要有动画。Teleport 只是调整 DOM 位置它本身不做过渡动画所以最终结构应该是 Teleport 包裹 Transition 再包裹内容节点Teleport :tohost Transition namemodal-fade after-leavehandleAfterLeave div v-ifvisible classmodal-mask div classmodal-container slot / /div /div /Transition /Teleportafter-leave是关闭动画真正结束的时刻。前面说过宿主节点必须在这个钩子里才做释放否则动画会被瞬间截断。我遇到的另一个细节是如果v-if一开始就是false打开时想要出现动画需要在 Transition 上加上appear属性否则首次渲染会直接显示没有过渡效果。5.2 打开弹窗时锁滚动关闭时必须还原之前的滚动状态Modal 打开后用户应该不能滚动背景页面。最直观的做法是设置document.body.style.overflow hidden。但这样直接把原本的overflow值覆盖掉了如果用户页面上存在内联overflow: auto关闭弹窗时恢复就会出错。更稳妥的做法是保存旧值再还原function lockScroll() { const body document.body const oldOverflow body.style.overflow body.dataset.prevOverflow oldOverflow body.style.overflow hidden } function unlockScroll() { const body document.body const prev body.dataset.prevOverflow ?? body.style.overflow prev delete body.dataset.prevOverflow }多弹窗场景还要带引用计数第一个弹窗打开时锁滚动最后一个弹窗关闭时恢复滚动。中间层级的弹窗关闭不能贸然解锁否则底层弹窗还开着背景页面却已经可以滚动了。5.3 无障碍和焦点管理至少要把这三件事做对自研弹窗如果不做无障碍处理视觉上没问题但键盘用户和读屏软件用户的使用体验会很差。最基本的三件事在弹窗容器上加上roledialog和aria-modaltrue告诉辅助技术这是一个模态对话框。弹窗打开时记录当前聚焦的元素关闭后还原焦点。否则关闭后焦点会跑回到 body用户键盘操作就会乱掉。监听Escape键关闭弹窗这是桌面端用户非常习惯的操作。简单的焦点还原实现是这样的let lastFocus: HTMLElement | null null onMounted(() { lastFocus document.activeElement as HTMLElement | null }) onBeforeUnmount(() { lastFocus?.focus() })如果弹窗内有关闭按钮最好打开后默认聚焦关闭按钮让键盘用户能直接走 Tab 循环。完整实现 focus trap 还需要拦截 Tab 键把焦点限制在弹窗内部逻辑稍微复杂但不难理解。我通常先在基本焦点还原的基础上跑通功能再根据产品需要决定加不加完整 focus trap避免一上来就把组件复杂度顶上去。6. 顺带说说如何给 Modal 组件补充全局类型声明TypeScript 项目里如果 Modal 组件通过app.component(BaseModal)全局注册模板里直接用却没有类型提示会让前面的类型工作打折扣。解决办法是在项目的types/目录下补充全局组件声明。这也是网上问得比较多的问题types 文件夹里的声明文件到底怎么写。以我的组件库为例在src/types/global-components.d.ts里写import type { ModalProps } from ./modal declare module vue { export interface GlobalComponents { BaseModal: { props: ModalProps emits: { (e: update:modelValue, value: boolean): void (e: open): void (e: close): void (e: closed): void } } } } export {}有了这段声明任何组件文件里直接用BaseModal v-modelshow /都能拿到完整的 props 和事件提示。配合前面定义的ModalProps整个组件体系从业务调用到内部实现全部处于类型约束之下后续同事接手也能很快找到所有字段定义的位置。实际项目中我还把ModalProps、ConfirmModalProps、LoadingController这些类型集中在types/modal.ts和types/loading.ts全局声明文件只负责映射到组件。这样比把所有类型堆在一个.d.ts里更清晰维护起来也方便。热词里经常看到“TypeScript types 文件夹的声明文件如何使用”这类问题本质就是理解.d.ts只做类型声明不产出运行时代码把类型定义和运行逻辑分开项目结构就清楚很多。至少在我自己项目里这套做法已经跑了两个完整业务周期弹窗相关的 bug 比原来少了大半。Modal 和 Loading 的代码量本身不大但要把 teleport 的容器管理、组件的自动化清理、动画时序和类型约束都安排明白还是需要沉下心来把每个环节的边界想清楚。希望这篇分享能把最关键的几条经验给你带到。
