Vue3 Teleport传送门组件与Suspense异步组件加载实战

Teleport组件解决DOM挂载位置问题

开发弹窗、抽屉、Toast通知等覆盖层组件时，最头疼的问题不是样式，而是DOM层级。如果组件挂载在某个overflow:hidden的父容器内，z-index无论设多高都无法突破父容器溢出隐藏。Teleport让组件的逻辑留在当前组件树中（响应式数据、props、emit正常工作），DOM却渲染到指定的目标位置。

<template>
  <button @click="showModal = true">打开弹窗</button>

  <Teleport to="body">
    <div v-if="showModal" class="modal-overlay" @click.self="showModal = false">
      <div class="modal-content">
        <h3>确认删除</h3>
        <p>此操作不可恢复，确定要继续吗？</p>
        <button @click="handleConfirm">确定</button>
        <button @click="showModal = false">取消</button>
      </div>
    </div>
  </Teleport>
</template>

to属性接收CSS选择器字符串或DOM元素引用，最常见的值是body。多个Teleport目标相同时，按组件渲染顺序依次追加到目标容器末尾。disabled属性设为true时，Teleport退化为普通渲染（DOM留在当前位置），适合某些条件下才需要传送的场景。

Teleport在嵌套弹窗与全屏遮罩中的应用

嵌套弹窗场景：两个弹窗组件各有一个Teleport到body的遮罩层，后渲染的遮罩自然覆盖前一个。关闭顺序由组件自身状态控制，无需手动管理z-index堆叠。

<!-- DialogA.vue -->
<Teleport to="body">
  <div class="modal-overlay">
    <div class="modal">弹窗A内容</div>
  </div>
</Teleport>

<!-- DialogB.vue -->
<Teleport to="body">
  <div class="modal-overlay">
    <div class="modal">弹窗B内容（自然在A之上）</div>
  </div>
</Teleport>

全屏Loading场景：在App.vue根节点放一个Teleport到body的全屏Loading组件，配合Pinia状态管理，任何子组件都能通过store.loading控制显示。因为DOM直接挂在body上，不存在被父容器overflow截断的问题。

Suspense组件处理异步依赖加载

Vue3的Suspense用于协调异步依赖——在所有异步子组件准备就绪前显示fallback内容。典型场景：异步组件加载、异步setup函数、异步数据请求。

<template>
  <Suspense>
    <template #default>
      <AsyncDashboard />
    </template>
    <template #fallback>
      <div class="skeleton-loader">
        <div class="skeleton-line" v-for="i in 5" :key="i"></div>
      </div>
    </template>
  </Suspense>
</template>

<script setup>
import { defineAsyncComponent } from 'vue'

const AsyncDashboard = defineAsyncComponent(() => import('./Dashboard.vue'))
</script>

当Dashboard.vue的setup中使用了顶层await时，Suspense自动捕获该异步依赖，在Promise resolve前渲染fallback插槽。

async setup与Suspense协作的实战模式

子组件在setup中使用顶层await等待数据加载完成：

<!-- Dashboard.vue -->
<script setup>
const { data, error } = await useFetch('/api/dashboard/stats')
const chartData = computed(() => transformData(data.value))
</script>

<template>
  <div class="dashboard">
    <StatsCard :data="chartData" />
  </div>
</template>

顶层await让组件的整个setup成为异步函数，Suspense在setup的Promise resolve前渲染fallback。数据获取逻辑和组件渲染解耦，不需要手动管理loading状态。配合SWR策略（stale-while-revalidate），useFetch先返回缓存数据再后台更新，用户体验更流畅。

组合Teleport与Suspense构建高级UI模式

弹窗内加载异步内容时，Teleport负责DOM位置，Suspense负责加载状态：

<Teleport to="body">
  <div v-if="visible" class="modal-overlay">
    <div class="modal">
      <Suspense>
        <template #default>
          <AsyncDetailModal :id="currentId" />
        </template>
        <template #fallback>
          <div class="modal-skeleton">
            <div class="skeleton-avatar"></div>
            <div class="skeleton-text"></div>
          </div>
        </template>
      </Suspense>
    </div>
  </div>
</Teleport>

这种模式在管理后台的详情弹窗中极常见：点击列表行打开弹窗，弹窗DOM挂在body上避免层级问题，内部异步加载详情数据时显示骨架屏。两个特性组合起来覆盖了全流程。

Suspense错误处理与生产环境注意事项

Suspense目前仍是实验性功能，Vue3.3+稳定了基本用法但event API可能变更。错误处理用onErrorCaptured或errorBoundary模式：

<script setup>
import { ref, onErrorCaptured } from 'vue'

const error = ref(null)

onErrorCaptured((err) => {
  error.value = err
  return false // 阻止错误继续冒泡
})
</script>

<template>
  <div v-if="error" class="error-fallback">
    <p>加载失败：{{ error.message }}</p>
    <button @click="error = null">重试</button>
  </div>
  <Suspense v-else>
    <template #default><AsyncContent /></template>
    <template #fallback><Skeleton /></template>
  </Suspense>
</template>

生产建议：仅在路由级别使用Suspense（配合vue-router的lazy loading），组件内部数据加载优先用watch + loading状态手动管理，避免Suspense嵌套导致的瀑布式加载。Suspense更适合做粗粒度的首屏等待，细粒度的局部加载状态用v-if +骨架屏更可控。