1. 基本概念

Teleport 是 Vue3 提供的一个内置组件，它可以将组件的内容传送到 DOM 树的任何位置，而不受组件层级的限制。这在处理模态框、通知、弹出菜单等需要突破组件层级限制的场景中特别有用。

1.1 基本语法

<template><teleport to="body"><!-- 这里的内容会被传送到 body 标签下 --><div class="modal"><!-- 模态框内容 --></div></teleport>
</template>

2. 常见使用场景

2.1 模态框

<!-- Modal.vue -->
<template><teleport to="body"><div v-if="isOpen" class="modal-overlay"><div class="modal"><div class="modal-header"><h3>{{ title }}</h3><button @click="close">×</button></div><div class="modal-body"><slot></slot></div><div class="modal-footer"><slot name="footer"><button @click="close">关闭</button></slot></div></div></div></teleport>
</template><script setup>
const props = defineProps({isOpen: Boolean,title: String
})const emit = defineEmits(['update:isOpen'])const close = () => {emit('update:isOpen', false)
}
</script><style scoped>
.modal-overlay {position: fixed;top: 0;left: 0;width: 100%;height: 100%;background: rgba(0, 0, 0, 0.5);display: flex;justify-content: center;align-items: center;z-index: 1000;
}.modal {background: white;padding: 20px;border-radius: 8px;min-width: 300px;
}
</style>

2.2 通知提示

<!-- Notification.vue -->
<template><teleport to="#notifications-container"><divv-if="show":class="['notification', type]"@click="close"><div class="notification-content">{{ message }}</div></div></teleport>
</template><script setup>
import { ref, onMounted } from 'vue'const props = defineProps({message: String,type: {type: String,default: 'info'},duration: {type: Number,default: 3000}
})const show = ref(true)const close = () => {show.value = false
}onMounted(() => {if (props.duration > 0) {setTimeout(close, props.duration)}
})
</script><style scoped>
.notification {position: fixed;top: 16px;right: 16px;padding: 12px 24px;border-radius: 4px;cursor: pointer;transition: all 0.3s;
}.info {background: #e6f7ff;border: 1px solid #91d5ff;
}.success {background: #f6ffed;border: 1px solid #b7eb8f;
}.error {background: #fff2f0;border: 1px solid #ffccc7;
}
</style>

2.3 上下文菜单

<!-- ContextMenu.vue -->
<template><teleport to="body"><divv-if="show"class="context-menu":style="position"><slot></slot></div></teleport>
</template><script setup>
import { ref, computed } from 'vue'const props = defineProps({show: Boolean,x: Number,y: Number
})const position = computed(() => ({left: props.x + 'px',top: props.y + 'px'
}))
</script><style scoped>
.context-menu {position: fixed;background: white;border: 1px solid #eee;border-radius: 4px;padding: 8px 0;min-width: 160px;box-shadow: 0 2px 12px rgba(0, 0, 0, 0.1);
}
</style>

3. 高级用法

3.1 动态目标

<template><teleport :to="target"><div class="content">动态传送的内容</div></teleport>
</template><script setup>
import { ref, onMounted } from 'vue'const target = ref('body')onMounted(() => {// 可以根据条件动态改变目标if (window.innerWidth < 768) {target.value = '#mobile-container'}
})
</script>

3.2 多个 Teleport 到同一目标

<template><teleport to="#notifications"><div class="notification">通知 1</div></teleport><teleport to="#notifications"><div class="notification">通知 2</div></teleport>
</template>

3.3 条件性传送

<template><teleport to="body" :disabled="isMobile"><div class="modal"><!-- 在移动端不会被传送，保持原位置 --></div></teleport>
</template><script setup>
import { ref, onMounted } from 'vue'const isMobile = ref(false)onMounted(() => {isMobile.value = window.innerWidth < 768window.addEventListener('resize', () => {isMobile.value = window.innerWidth < 768})
})
</script>

4. 实际应用示例

4.1 全局加载指示器

<!-- LoadingIndicator.vue -->
<template><teleport to="body"><div v-if="loading" class="loading-overlay"><div class="loading-spinner"></div><div class="loading-text">{{ message }}</div></div></teleport>
</template><script setup>
defineProps({loading: Boolean,message: {type: String,default: '加载中...'}
})
</script><style scoped>
.loading-overlay {position: fixed;top: 0;left: 0;width: 100%;height: 100%;background: rgba(255, 255, 255, 0.9);display: flex;flex-direction: column;justify-content: center;align-items: center;z-index: 9999;
}
</style>

4.2 图片预览器

<!-- ImageViewer.vue -->
<template><teleport to="body"><divv-if="visible"class="image-viewer"@click="close"><img:src="imageUrl"@click.stop><div class="controls"><button @click.stop="prev">&lt;</button><button @click.stop="next">&gt;</button></div></div></teleport>
</template><script setup>
const props = defineProps({visible: Boolean,imageUrl: String,images: Array
})const emit = defineEmits(['update:visible'])const close = () => {emit('update:visible', false)
}const prev = () => {// 实现上一张逻辑
}const next = () => {// 实现下一张逻辑
}
</script>

5. 最佳实践

5.1 目标元素管理

<!-- index.html -->
<!DOCTYPE html>
<html>
<head><title>Vue App</title>
</head>
<body><div id="app"></div><!-- 为 Teleport 预留的容器 --><div id="modals"></div><div id="notifications"></div><div id="tooltips"></div>
</body>
</html>

5.2 组件封装

<!-- BaseModal.vue -->
<template><teleport to="#modals"><transition name="modal"><divv-if="modelValue"class="modal-container"@click.self="close"><div class="modal-content"><slot></slot></div></div></transition></teleport>
</template><script setup>
defineProps({modelValue: Boolean
})const emit = defineEmits(['update:modelValue'])const close = () => {emit('update:modelValue', false)
}
</script>

6. 注意事项

1. 目标元素存在性检查

<template><teleport to="#target" :disabled="!targetExists"><div>内容</div></teleport>
</template><script setup>
import { ref, onMounted } from 'vue'const targetExists = ref(false)onMounted(() => {targetExists.value = !!document.querySelector('#target')
})
</script>

2. SSR 兼容性

<template><client-only><teleport to="body"><div>仅客户端渲染的内容</div></teleport></client-only>
</template>

3. 清理工作

<script setup>
import { onUnmounted } from 'vue'onUnmounted(() => {// 确保清理所有传送的内容const target = document.querySelector('#target')if (target) {target.innerHTML = ''}
})
</script>