Teleport 与 Suspense：组件树和 DOM 树是两张图

<template>
  <header class="site-header">...</header>   <!-- z-index: 10 -->
  <main>
    <button @click="open = true">打开弹窗</button>
    <div v-if="open" class="modal">...</div>  <!-- z-index: 100，却被压住 -->
  </main>
</template>

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

  <Teleport to="body">
    <div v-if="showModal" class="modal">
      <p>模态框内容</p>
      <button @click="showModal = false">关闭</button>
    </div>
  </Teleport>
</template>

<Teleport to="body">...</Teleport>
<Teleport to="#modals">...</Teleport>       <!-- 提前在 index.html 里放好容器 -->
<Teleport :to="containerEl">...</Teleport>  <!-- 运行时拿到的元素 -->

Failed to locate Teleport target with selector "#modals"

<!-- 对策一：把目标容器放在组件渲染之前就存在的位置（如 index.html） -->
<!-- 对策二：Vue 3.5+ 用 defer，把传送推迟到同轮渲染的其余部分解析完 -->
<Teleport to="#modals" defer>
  <Modal />
</Teleport>

<Teleport to="body" :disabled="isMobile">
  <Modal />
</Teleport>

<div id="panel" @click="log('panel 被点到')">
  <Teleport to="body">
    <button @click="log('button 被点到')">点我</button>
  </Teleport>
</div>

<!-- Profile.vue -->
<script setup>
const user = await fetchUser(route.params.id);   // async setup
</script>

<template>{{ user.name }}</template>

Component inside <Transition> renders non-element root node...
<AsyncSetup> - an async setup() must be surrounded by <Suspense>...

<template>
  <Suspense>
    <Profile />                     <!-- 内部有 async setup 的组件 -->
    <template #fallback>
      <UserSkeleton />
    </template>
  </Suspense>
</template>

<Suspense @pending="onPending" @resolve="onResolve" @fallback="onFallback">
  <Profile />
  <template #fallback><UserSkeleton /></template>
</Suspense>

<script setup>
import { ref, onErrorCaptured } from 'vue';
const error = ref(null);
onErrorCaptured((err) => { error.value = err; return false; });
</script>

<template>
  <ErrorBanner v-if="error" :error="error" @retry="reload" />
  <Suspense v-else>
    <Profile :key="reloadKey" />
    <template #fallback><UserSkeleton /></template>
  </Suspense>
</template>

<template>
  <Suspense>
    <template #default>
      <Header />
      <Suspense>
        <Dashboard />
        <template #fallback><WidgetSkeleton /></template>
      </Suspense>
      <Footer />
    </template>
    <template #fallback>
      <PageSkeleton />
    </template>
  </Suspense>
</template>

<!-- AppModal.vue -->
<template>
  <Teleport to="body">
    <Transition name="modal">
      <div v-if="isOpen" class="modal-mask" @click.self="emit('close')">
        <div class="modal-card" role="dialog" aria-modal="true">
          <slot />
          <button class="modal-close" @click="emit('close')">关闭</button>
        </div>
      </div>
    </Transition>
  </Teleport>
</template>

<script setup>
defineProps({ isOpen: Boolean });
const emit = defineEmits(['close']);
</script>

<style>
.modal-enter-active, .modal-leave-active { transition: opacity 0.25s; }
.modal-enter-from, .modal-leave-to { opacity: 0; }
.modal-mask { position: fixed; inset: 0; background: rgb(0 0 0 / 0.4);
  display: grid; place-items: center; z-index: 1000; }
</style>

// modal-manager.ts
import { reactive } from 'vue'

interface ModalEntry {
  id: number
  component: object
  props: Record<string, unknown>
}

export const modalState = reactive<{ stack: ModalEntry[] }>({ stack: [] })
let nextId = 1

export function openModal(component: object, props: Record<string, unknown> = {}) {
  const id = nextId++
  modalState.stack.push({ id, component, props })   // 后打开的在栈顶 = 视觉上层
  return id
}

export function closeModal(id: number) {
  const idx = modalState.stack.findIndex((m) => m.id === id)
  if (idx !== -1) modalState.stack.splice(idx, 1)
}

<!-- ModalHost.vue：挂在 App 根部，全站唯一的弹窗渲染出口 -->
<template>
  <Teleport to="body">
    <AppModal v-for="m in modalState.stack" :key="m.id" v-bind="m.props">
      <component :is="m.component" @close="closeModal(m.id)" />
    </AppModal>
  </Teleport>
</template>

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

const isMobile = ref(false)
let mql
onMounted(() => {
  mql = window.matchMedia('(max-width: 768px)')
  isMobile.value = mql.matches
  mql.addEventListener('change', (e) => (isMobile.value = e.matches))   // addListener 已废弃
})
onBeforeUnmount(() => mql?.removeEventListener('change', () => {}))
</script>

<template>
  <Teleport to="body" :disabled="isMobile">
    <div :class="isMobile ? 'drawer' : 'modal'">...</div>
  </Teleport>
</template>

<template>
  <div id="wrap" @click="log('wrap')">
    <Teleport to="body">
      <button @click="log('btn')">点我</button>
    </Teleport>
  </div>
  <p @click="log('p')">我是 body 下的另一个元素</p>
</template>

<script setup>
import { watch, onBeforeUnmount } from 'vue';

const props = defineProps({ isOpen: Boolean });
const emit = defineEmits(['close']);
let triggerEl = null;

function onKeydown(e) {
  if (e.key === 'Escape') emit('close');
}

watch(() => props.isOpen, (open) => {
  document.body.style.overflow = open ? 'hidden' : '';
  if (open) {
    triggerEl = document.activeElement;
    document.addEventListener('keydown', onKeydown);
  } else {
    document.removeEventListener('keydown', onKeydown);
    triggerEl?.focus?.();
  }
});

onBeforeUnmount(() => {
  document.removeEventListener('keydown', onKeydown);
  document.body.style.overflow = '';
});
</script>

<!-- App.vue -->
<template>
  <Dashboard />        <!-- Dashboard 的 <script setup> 里有 await fetchUser() -->
</template>

import { h, onMounted, onBeforeUnmount, ref } from 'vue';

export function usePortal(Comp) {
  const target = ref(null);
  const owned = { value: false };

  onMounted(() => {
    let el = document.querySelector('#portal-root');
    if (!el) {
      el = document.createElement('div');
      el.id = 'portal-root';
      document.body.appendChild(el);
      owned.value = true;
    }
    target.value = el;
  });

  onBeforeUnmount(() => {
    if (owned.value && target.value) target.value.remove();
  });

  return () => (target.value ? h(Teleport, { to: target.value }, () => h(Comp)) : null);
}