Vue3 完全指南

什么是 Teleport？

Teleport 是 Vue3 中的一个内置组件，用于将组件的内容渲染到 DOM 树中的其他位置，而不是当前组件的 DOM 结构中。这对于模态框、通知、弹出菜单等需要突破组件层级限制的场景非常有用。

1. 基本用法

Teleport 组件使用 to 属性指定要渲染到的目标位置，该属性可以是 CSS 选择器或 DOM 元素。

<template>
  <div class="app">
    <h1>应用内容</h1>
    <button @click="showModal = true">显示模态框</button>
    
    <!-- Teleport 组件将内容渲染到 body 末尾 -->
    <Teleport to="body">
      <div v-if="showModal" class="modal-overlay">
        <div class="modal">
          <h2>模态框标题</h2>
          <p>这是一个使用 Teleport 渲染的模态框</p>
          <button @click="showModal = false">关闭</button>
        </div>
      </div>
    </Teleport>
  </div>
</template>

<script setup>
import { ref } from 'vue';

const showModal = ref(false);
</script>

<style scoped>
.app {
  padding: 20px;
}

.modal-overlay {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  background-color: rgba(0, 0, 0, 0.5);
  display: flex;
  justify-content: center;
  align-items: center;
  z-index: 1000;
}

.modal {
  background-color: white;
  padding: 20px;
  border-radius: 8px;
  box-shadow: 0 2px 10px rgba(0, 0, 0, 0.2);
}
</style>

2. 目标位置

Teleport 的 to 属性可以接受多种类型的值：

<!-- CSS 选择器 -->
<Teleport to="#app">内容</Teleport>
<Teleport to=".modal-container">内容</Teleport>
<Teleport to="body">内容</Teleport>

<!-- DOM 元素 -->
<Teleport :to="document.body">内容</Teleport>
<Teleport :to="modalContainerRef">内容</Teleport>

3. 禁用 Teleport

可以使用 disabled 属性禁用 Teleport，此时内容会渲染到当前组件的 DOM 结构中。

<template>
  <div>
    <button @click="isTeleportDisabled = !isTeleportDisabled">
      {{ isTeleportDisabled ? '启用 Teleport' : '禁用 Teleport' }}
    </button>
    
    <Teleport to="body" :disabled="isTeleportDisabled">
      <div class="teleport-content">
        这是 Teleport 内容
      </div>
    </Teleport>
  </div>
</template>

<script setup>
import { ref } from 'vue';

const isTeleportDisabled = ref(false);
</script>

4. Teleport 与组件

Teleport 可以包含组件，组件的生命周期和事件处理与普通组件相同。

<template>
  <div>
    <button @click="showNotification = true">显示通知</button>
    
    <Teleport to="body">
      <Notification 
        v-if="showNotification" 
        message="这是一条通知" 
        @close="showNotification = false" 
      />
    </Teleport>
  </div>
</template>

<script setup>
import { ref } from 'vue';
import Notification from './Notification.vue';

const showNotification = ref(false);
</script>

<template>
  <div class="notification">
    <p>{{ message }}</p>
    <button @click="$emit('close')">×</button>
  </div>
</template>

<script setup>
defineProps({
  message: {
    type: String,
    required: true
  }
});

defineEmits(['close']);
</script>

<style scoped>
.notification {
  position: fixed;
  top: 20px;
  right: 20px;
  background-color: #42b883;
  color: white;
  padding: 15px 20px;
  border-radius: 4px;
  box-shadow: 0 2px 10px rgba(0, 0, 0, 0.2);
  display: flex;
  justify-content: space-between;
  align-items: center;
  min-width: 300px;
}

.notification button {
  background: none;
  border: none;
  color: white;
  font-size: 1.2rem;
  cursor: pointer;
  padding: 0;
  margin-left: 10px;
}
</style>

5. Teleport 的使用场景

• 模态框（Modal）
• 通知（Notification）
• 弹出菜单（Dropdown Menu）
• 加载指示器（Loading Indicator）
• 全局提示（Toast）
• 全屏覆盖（Fullscreen Overlay）

6. Teleport 的最佳实践

• 只在必要时使用 Teleport，避免过度使用
• 使用语义化的目标位置，如 body 或专门的容器元素
• 为 Teleport 内容添加适当的 z-index，避免被其他元素遮挡
• 考虑响应式设计，确保在不同设备上都能正常显示
• 使用 CSS 过渡或动画提升用户体验
• 注意 Teleport 内容的事件冒泡，可能会影响到父组件

7. Teleport 与 CSS 作用域

Teleport 内容的样式会受到父组件的 scoped CSS 影响吗？答案是不会。因为 Teleport 内容渲染到了其他位置，父组件的 scoped CSS 不会应用到 Teleport 内容上。

<template>
  <div>
    <Teleport to="body">
      <div class="teleport-content">
        Teleport 内容
      </div>
    </Teleport>
    
    <div class="local-content">
      本地内容
    </div>
  </div>
</template>

<style scoped>
/* 只应用于本地内容，不应用于 Teleport 内容 */
.teleport-content {
  color: red;
}

.local-content {
  color: blue;
}
</style>

<style>
/* 全局样式，应用于所有匹配的元素 */
.teleport-content {
  color: green;
}
</style>

8. Teleport 与 SSR

在服务器端渲染（SSR）中，Teleport 的行为会有所不同。由于服务器端没有 DOM，Teleport 内容会被渲染到当前组件的 HTML 中，然后在客户端 hydration 时被移动到目标位置。

// 服务器端渲染输出
<div class="app">
  <h1>应用内容</h1>
  <!-- Teleport 内容被渲染到当前位置 -->
  <div class="modal-overlay">
    <div class="modal">
      <h2>模态框标题</h2>
      <p>这是一个使用 Teleport 渲染的模态框</p>
      <button>关闭</button>
    </div>
  </div>
</div>

// 客户端 hydration 后，内容被移动到 body 末尾
<body>
  <div class="app">
    <h1>应用内容</h1>
  </div>
  <div class="modal-overlay">
    <div class="modal">
      <h2>模态框标题</h2>
      <p>这是一个使用 Teleport 渲染的模态框</p>
      <button>关闭</button>
    </div>
  </div>
</body>