Vue 教程：使用 Teleport 构建模态框、通知与浮层组件

快速概述

在 Vue 3 中，Teleport 是解决组件渲染位置与逻辑归属不一致问题的内置组件。它允许开发者将模板片段传送到 body 或其他任意 DOM 节点下渲染，同时保留组件内部的响应式数据与事件通信。该技术主要适用于模态框、通知提示、下拉浮层、右键菜单等需要脱离父级容器（避免 overflow: hidden 裁剪或 z-index 层级失效）的场景。前置环境要求：Vue 3.0+ 版本，且无需额外安装依赖。

核心概念与原理

Teleport 的工作流程非常直接：通过 to 属性指定目标容器（CSS 选择器字符串或 DOM 元素），组件挂载时，Vue 会将插槽内容移动到目标节点下渲染。其核心价值在于：逻辑归组件，DOM 归全局。这意味着，即便模态框的模板被传送到 body，其内部使用的 ref、props、emit 依然与父组件保持完整的响应式连接。此外，disabled 属性可动态控制是否启用传送，便于在特定路由或布局下回退到原位渲染。

实战步骤与代码

1. 基础模态框组件

创建一个 BaseModal.vue，核心逻辑如下：

<template>
  <Teleport to="body">
    <div v-if="visible" class="modal-overlay" @click.self="close">
      <div class="modal-content">
        <slot /> <!-- 插槽内容仍由父组件控制 -->
      </div>
    </div>
  </Teleport>
</template>
<script setup> defineProps({ visible: Boolean }); const emit = defineEmits(['update:visible']); const close = () => emit('update:visible', false); </script>
<style scoped> .modal-overlay { position: fixed; inset: 0; background: rgba(0,0,0,.5); z-index: 1000; } .modal-content { position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); background: #fff; padding: 24px; border-radius: 8px; } </style>

注意：虽然样式是 scoped，但 Teleport 渲染到 body 后，Vue 会自动将作用域属性添加到传送的 DOM 上，样式依然生效。

2. 通知通知组件

通知组件通常需要动态挂载多个实例。推荐使用函数式调用配合 createApp 实现：

// notification.js
import { createApp, h } from 'vue';
import Notification from './Notification.vue';
export function notify(message, type = 'info') { const container = document.createElement('div'); document.body.appendChild(container); const app = createApp({ render() { return h(Notification, { message, type, onClose: () => { app.unmount(); container.remove(); } }); } }); app.mount(container); }

在 Notification.vue 内部使用 <Teleport to="body"> 确保通知浮层始终位于页面最顶层。

3. 浮层定位组件

对于下拉菜单或工具提示，需要动态计算位置。结合 Teleport 与 getBoundingClientRect：

<Teleport to="body">
  <div v-if="show" :style="{ position: 'fixed', top: top + 'px', left: left + 'px' }">
    <slot />
  </div>
</Teleport>

在触发元素上监听滚动与 resize 事件，实时更新 top 与 left 值，即可实现跟随定位。

常见坑点与优化

• SSR 报错：服务端渲染时 document 不存在，需使用 <ClientOnly> 包裹或判断 typeof window !== 'undefined'。
• 样式污染：全局样式需添加特定前缀类名，避免影响业务页面。
• 层级冲突：多个 Teleport 组件同时存在时，统一管理 z-index 变量，避免硬编码。
• 性能优化：频繁切换显示状态时，使用 v-if 配合 transition 动画，并在关闭后延迟销毁组件以复用实例。