Vue3 Teleport组件深度解析与模态框实战封装

Teleport组件解决的核心DOM挂载问题

Vue3的Teleport组件解决的是组件逻辑归属与DOM渲染位置的分离问题。在常规组件树中，子组件的DOM节点严格遵循父组件的嵌套关系渲染，这在模态框、通知栏、悬浮菜单等场景下会产生问题：父组件的overflow:hidden、z-index层级、transform属性都会影响子组件的定位和层叠表现。

Teleport的核心原理是：在组件的逻辑树中保持父子关系（数据传递、provide/inject、事件冒泡均正常工作），但在DOM树中将子节点渲染到指定的目标容器中。

Teleport基础用法与渲染行为

<template>
  <button @click="showModal = true">打开模态框</button>
  
  <Teleport to="body">
    <div v-if="showModal" class="modal-overlay">
      <div class="modal-content">
        <h2>模态框标题</h2>
        <p>内容区域</p>
        <button @click="showModal = false">关闭</button>
      </div>
    </div>
  </Teleport>
</template>

to属性接受CSS选择器字符串或DOM元素引用。渲染后，modal-overlay会被挂载到body下，而不是button的同级位置。关键行为：如果目标容器不存在，Teleport会静默失败（开发模式下会有警告）；如果目标容器已存在内容，Teleport会追加而非替换。

模态框组件的完整封装方案

生产级模态框需要处理遮罩层点击关闭、ESC键关闭、打开时锁定背景滚动、关闭时恢复滚动位置、打开动画和关闭动画等多个交互细节。

<!-- Modal.vue -->
<script setup>
import { watch, ref, onMounted, onUnmounted } from 'vue'

const props = defineProps({
  modelValue: { type: Boolean, default: false },
  closeOnClickOverlay: { type: Boolean, default: true },
  closeOnEsc: { type: Boolean, default: true },
  zIndex: { type: Number, default: 1000 }
})

const emit = defineEmits(['update:modelValue'])
const scrollBarWidth = ref(0)
let savedScrollY = 0

function lockScroll() {
  savedScrollY = window.scrollY
  scrollBarWidth.value = window.innerWidth - document.documentElement.clientWidth
  document.body.style.overflow = 'hidden'
  document.body.style.paddingRight = scrollBarWidth.value + 'px'
  document.body.style.position = 'fixed'
  document.body.style.top = `-${savedScrollY}px`
  document.body.style.width = '100%'
}

function unlockScroll() {
  document.body.style.overflow = ''
  document.body.style.paddingRight = ''
  document.body.style.position = ''
  document.body.style.top = ''
  document.body.style.width = ''
  window.scrollTo(0, savedScrollY)
}

function handleKeydown(e) {
  if (e.key === 'Escape' && props.closeOnEsc && props.modelValue) {
    emit('update:modelValue', false)
  }
}

watch(() => props.modelValue, (val) => {
  if (val) lockScroll()
  else unlockScroll()
})

onMounted(() => document.addEventListener('keydown', handleKeydown))
onUnmounted(() => {
  document.removeEventListener('keydown', handleKeydown)
  unlockScroll()
})
</script>

多层Teleport的堆叠管理

当多个模态框同时打开时，z-index管理变得关键。Vue3不内置z-index管理，需要在组件层面实现堆叠计数器：

// useModalStack.js
import { ref } from 'vue'
const stackDepth = ref(0)
const BASE_Z_INDEX = 1000

export function useModalStack() {
  function open() {
    stackDepth.value++
    return BASE_Z_INDEX + stackDepth.value * 10
  }
  function close() {
    stackDepth.value = Math.max(0, stackDepth.value - 1)
  }
  return { stackDepth, open, close }
}

每次打开模态框时调用open()获取当前z-index，关闭时调用close()递减计数器。这样多层模态框的层叠顺序始终保持正确。

Teleport在SSR中的注意事项

SSR场景下，Teleport的目标容器在服务端渲染时不存在（因为服务端没有真实DOM）。Vue3通过hydration机制处理这一问题：服务端渲染时Teleport的内容被暂存，客户端hydration完成后再挂载到目标容器。需要确保目标容器在hydration之前已经存在于DOM中，否则Teleport的内容会被丢弃。推荐在App.vue的template中预置目标容器：

<!-- App.vue -->
<template>
  <div id="app">
    <RouterView />
  </div>
  <div id="teleport-target"></div>
</template>

<!-- 子组件中使用 -->
<Teleport to="#teleport-target">
  <!-- 模态框内容 -->
</Teleport>

这种模式在SSR和CSR环境下都能正常工作，且Teleport目标的挂载点集中管理，便于调试和维护。