目錄
基本用法?
搭配組件使用?
禁用 Teleport?
多個 Teleport 共享目標?
延遲解析的 Teleport??
總結
<Teleport>?是一個內置組件，它可以將一個組件內部的一部分模板“傳送”到該組件的 DOM 結構外層的位置去。
基本用法?
有時我們可能會遇到這樣的場景：一個組件模板的一部分在邏輯上從屬于該組件，但從整個應用視圖的角度來看，它在 DOM 中應該被渲染在其他地方，甚至在整個 Vue 應用外部。
這類場景最常見的例子就是全屏的模態框。理想情況下，我們希望觸發模態框的按鈕和模態框本身的代碼是在同一個單文件組件中，因為它們都與組件的開關狀態有關。但這意味著該模態框將與按鈕一起渲染在應用 DOM 結構里很深的地方。這會導致該模態框的 CSS 布局代碼很難寫。
試想下面這樣的 HTML 結構：
<div class="outer"><h3>Tooltips with Vue 3 Teleport</h3><div><MyModal /></div>
</div>接下來我們來看看?<MyModal>?的實現：
<script setup>
import { ref } from 'vue'const open = ref(false)
</script><template><button @click="open = true">Open Modal</button><div v-if="open" class="modal"><p>Hello from the modal!</p><button @click="open = false">Close</button></div>
</template><style scoped>
.modal {position: fixed;z-index: 999;top: 20%;left: 50%;width: 300px;margin-left: -150px;
}
</style>這個組件中有一個?<button>?按鈕來觸發打開模態框，和一個 class 名為?.modal?的?<div>，它包含了模態框的內容和一個用來關閉的按鈕。
當在初始 HTML 結構中使用這個組件時，會有一些潛在的問題：
-
position: fixed?能夠相對于瀏覽器窗口放置有一個條件，那就是不能有任何祖先元素設置了?transform、perspective?或者?filter?樣式屬性。也就是說如果我們想要用 CSS?transform?為祖先節點?<div class="outer">?設置動畫，就會不小心破壞模態框的布局！ -
這個模態框的?
z-index?受限于它的容器元素。如果有其他元素與?<div class="outer">?重疊并有更高的?z-index，則它會覆蓋住我們的模態框。
<Teleport>?提供了一個更簡單的方式來解決此類問題，讓我們不需要再顧慮 DOM 結構的問題。讓我們用?<Teleport>?改寫一下?<MyModal>：
<button @click="open = true">Open Modal</button><Teleport to="body"><div v-if="open" class="modal"><p>Hello from the modal!</p><button @click="open = false">Close</button></div>
</Teleport><Teleport>?接收一個?to?prop 來指定傳送的目標。to?的值可以是一個 CSS 選擇器字符串，也可以是一個 DOM 元素對象。這段代碼的作用就是告訴 Vue“把以下模板片段傳送到?body?標簽下”。
你可以點擊下面這個按鈕，然后通過瀏覽器的開發者工具，在?<body>?標簽下找到模態框元素：
<!DOCTYPE html>
<html lang="zh-CN">
<head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Vue 3 模態框演示</title><!-- 引入 Vue 3 CDN --><script src="https://unpkg.com/vue@3/dist/vue.global.js"></script><style>* {margin: 0;padding: 0;box-sizing: border-box;font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;}body {background: linear-gradient(135deg, #1a2a6c, #b21f1f, #fdbb2d);min-height: 100vh;display: flex;flex-direction: column;align-items: center;padding: 40px 20px;color: #fff;}.container {max-width: 1000px;width: 100%;text-align: center;}header {margin-bottom: 40px;}h1 {font-size: 3rem;margin-bottom: 10px;text-shadow: 0 2px 10px rgba(0,0,0,0.2);}.subtitle {font-size: 1.2rem;opacity: 0.9;max-width: 600px;margin: 0 auto;}.features {display: flex;justify-content: center;gap: 30px;margin: 50px 0;flex-wrap: wrap;}.feature-card {background: rgba(255, 255, 255, 0.1);backdrop-filter: blur(10px);border-radius: 15px;padding: 25px;width: 250px;box-shadow: 0 8px 32px rgba(0, 0, 0, 0.2);border: 1px solid rgba(255, 255, 255, 0.18);transition: transform 0.3s ease;}.feature-card:hover {transform: translateY(-10px);}.feature-icon {font-size: 3rem;margin-bottom: 20px;color: #fdbb2d;}.feature-title {font-size: 1.5rem;margin-bottom: 15px;}.feature-desc {font-size: 1rem;opacity: 0.8;}.open-modal-btn {background: linear-gradient(to right, #ff416c, #ff4b2b);color: white;border: none;padding: 16px 40px;font-size: 1.2rem;border-radius: 50px;cursor: pointer;transition: all 0.3s ease;box-shadow: 0 4px 20px rgba(255, 75, 43, 0.4);margin: 20px 0;font-weight: bold;letter-spacing: 1px;}.open-modal-btn:hover {transform: translateY(-3px);box-shadow: 0 6px 25px rgba(255, 75, 43, 0.6);}.open-modal-btn:active {transform: translateY(1px);}.instructions {background: rgba(0, 0, 0, 0.2);padding: 25px;border-radius: 15px;max-width: 700px;margin: 40px auto;text-align: left;}.instructions h2 {margin-bottom: 15px;text-align: center;}.instructions code {background: rgba(0, 0, 0, 0.3);padding: 2px 8px;border-radius: 4px;font-family: monospace;}/* 模態框樣式 */.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: 9999;}.modal-container {background: linear-gradient(to bottom right, #2c3e50, #1a1a2e);border-radius: 15px;width: 90%;max-width: 500px;padding: 30px;box-shadow: 0 10px 50px rgba(0, 0, 0, 0.3);position: relative;transform: scale(0.95);opacity: 0;animation: modalAppear 0.4s forwards;}@keyframes modalAppear {to {transform: scale(1);opacity: 1;}}.modal-header {text-align: center;margin-bottom: 25px;}.modal-header h2 {font-size: 2rem;color: #fdbb2d;margin-bottom: 10px;}.modal-content {margin-bottom: 30px;line-height: 1.6;font-size: 1.1rem;}.modal-footer {display: flex;justify-content: center;gap: 15px;}.modal-btn {padding: 12px 30px;border: none;border-radius: 8px;font-size: 1rem;font-weight: bold;cursor: pointer;transition: all 0.2s ease;}.close-btn {background: linear-gradient(to right, #ff416c, #ff4b2b);color: white;}.action-btn {background: linear-gradient(to right, #00b09b, #96c93d);color: white;}.modal-btn:hover {transform: translateY(-2px);box-shadow: 0 4px 15px rgba(0, 0, 0, 0.2);}footer {margin-top: 50px;opacity: 0.7;font-size: 0.9rem;}@media (max-width: 768px) {.features {flex-direction: column;align-items: center;}h1 {font-size: 2.2rem;}}</style>
</head>
<body><div id="app"><div class="container"><header><h1>Vue 3 模態框演示</h1><p class="subtitle">使用Vue 3的Teleport組件創建高性能模態框，實現內容渲染到body元素</p></header><div class="features"><div class="feature-card"><div class="feature-icon">🚀</div><h3 class="feature-title">Teleport 特性</h3><p class="feature-desc">使用Teleport將模態框渲染到body元素，避免CSS層級問題</p></div><div class="feature-card"><div class="feature-icon">🎨</div><h3 class="feature-title">平滑動畫</h3><p class="feature-desc">CSS動畫實現模態框的平滑進入和退出效果</p></div><div class="feature-card"><div class="feature-icon">📱</div><h3 class="feature-title">響應式設計</h3><p class="feature-desc">適配各種屏幕尺寸，在移動設備上完美展示</p></div></div><button class="open-modal-btn" @click="open = true">打開模態框</button><div class="instructions"><h2>實現說明</h2><p>此演示使用Vue 3的Composition API和Teleport組件：</p><ul><li>使用<code><Teleport to="body"></code>將模態框渲染到body元素</li><li>通過<code>v-if</code>指令控制模態框的顯示/隱藏</li><li>使用CSS動畫實現模態框的平滑過渡效果</li><li>點擊模態框外部或關閉按鈕可關閉模態框</li><li>使用Vue 3的CDN版本，無需構建步驟</li></ul></div></div><!-- 使用Teleport將模態框渲染到body --><Teleport to="body"><div v-if="open" class="modal-overlay" @click.self="open = false"><div class="modal-container"><div class="modal-header"><h2>Vue 3 模態框</h2><p>使用Teleport實現</p></div><div class="modal-content"><p>這是一個使用Vue 3的Teleport組件創建的模態框示例。</p><p>模態框被渲染到body元素，避免了CSS層級問題，同時實現了平滑的動畫效果。</p><p>點擊外部區域、關閉按鈕或按ESC鍵都可以關閉此模態框。</p></div><div class="modal-footer"><button class="modal-btn action-btn">確認操作</button><button class="modal-btn close-btn" @click="open = false">關閉</button></div></div></div></Teleport><footer><p>Vue 3 模態框演示 © 2023</p></footer></div><script>const { createApp, ref } = VuecreateApp({setup() {const open = ref(false)// 添加鍵盤事件監聽const handleKeydown = (e) => {if (open.value && e.key === 'Escape') {open.value = false}}// 在組件掛載時添加事件監聽Vue.onMounted(() => {window.addEventListener('keydown', handleKeydown)})// 在組件卸載時移除事件監聽Vue.onUnmounted(() => {window.removeEventListener('keydown', handleKeydown)})return {open}}}).mount('#app')</script>
</body>
</html>TIP
<Teleport>?掛載時，傳送的?to?目標必須已經存在于 DOM 中。理想情況下，這應該是整個 Vue 應用 DOM 樹外部的一個元素。如果目標元素也是由 Vue 渲染的，你需要確保在掛載?<Teleport>?之前先掛載該元素。
我們也可以將?<Teleport>?和?<Transition>?結合使用來創建一個帶動畫的模態框。你可以看看這個示例。
搭配組件使用?
<Teleport>?只改變了渲染的 DOM 結構，它不會影響組件間的邏輯關系。也就是說，如果?<Teleport>?包含了一個組件，那么該組件始終和這個使用了?<Teleport>?的組件保持邏輯上的父子關系。傳入的 props 和觸發的事件也會照常工作。
這也意味著來自父組件的注入也會按預期工作，子組件將在 Vue Devtools 中嵌套在父級組件下面，而不是放在實際內容移動到的地方。
禁用 Teleport?
在某些場景下可能需要視情況禁用?<Teleport>。舉例來說，我們想要在桌面端將一個組件當做浮層來渲染，但在移動端則當作行內組件。我們可以通過對?<Teleport>?動態地傳入一個?disabled?prop 來處理這兩種不同情況：
<Teleport :disabled="isMobile">...
</Teleport>然后我們可以動態地更新?isMobile。
多個 Teleport 共享目標?
一個可重用的?<Modal>?組件可能同時存在多個實例。對于此類場景，多個?<Teleport>?組件可以將其內容掛載在同一個目標元素上，而順序就是簡單的順次追加，后掛載的將排在目標元素下更后面的位置上，但都在目標元素中。
比如下面這樣的用例：
<Teleport to="#modals"><div>A</div>
</Teleport>
<Teleport to="#modals"><div>B</div>
</Teleport>渲染的結果為：
<div id="modals"><div>A</div><div>B</div>
</div>
延遲解析的 Teleport??
在 Vue 3.5 及更高版本中，我們可以使用?defer?prop 推遲 Teleport 的目標解析，直到應用的其他部分掛載。這允許 Teleport 將由 Vue 渲染且位于組件樹之后部分的容器元素作為目標：
<Teleport defer to="#late-div">...</Teleport><!-- 稍后出現于模板中的某處 -->
<div id="late-div"></div>請注意，目標元素必須與 Teleport 在同一個掛載/更新周期內渲染，即如果?<div>?在一秒后才掛載，Teleport 仍然會報錯。延遲 Teleport 的原理與?mounted?生命周期鉤子類似。
總結
<!DOCTYPE html>
<html lang="zh-CN"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Vue 3 Teleport 特性演示</title><script src="https://unpkg.com/vue@3/dist/vue.global.js"></script><style>* {margin: 0;padding: 0;box-sizing: border-box;}body {font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);min-height: 100vh;padding: 20px;}.container {max-width: 800px;margin: 0 auto;background: white;border-radius: 10px;padding: 30px;box-shadow: 0 10px 30px rgba(0, 0, 0, 0.2);}h1 {text-align: center;color: #667eea;margin-bottom: 30px;}.demo-section {margin-bottom: 30px;padding: 20px;border: 1px solid #e1e8ed;border-radius: 8px;background: #f8f9fa;}.demo-section h2 {color: #333;margin-bottom: 15px;}.demo-section p {color: #666;margin-bottom: 15px;line-height: 1.6;}.btn {background: #667eea;color: white;border: none;padding: 10px 20px;border-radius: 5px;cursor: pointer;margin: 5px;transition: background 0.3s;}.btn:hover {background: #5a67d8;}.btn-danger {background: #e53e3e;}.btn-danger:hover {background: #c53030;}.code-block {background: #f1f5f9;padding: 15px;border-radius: 5px;font-family: 'Courier New', monospace;font-size: 14px;margin: 10px 0;border-left: 4px solid #667eea;white-space: pre-line;}/* 模態框樣式 */.modal-overlay {position: fixed;top: 0;left: 0;right: 0;bottom: 0;background: rgba(0, 0, 0, 0.5);display: flex;justify-content: center;align-items: center;z-index: 1000;}.modal {background: white;border-radius: 8px;padding: 20px;max-width: 400px;width: 90%;box-shadow: 0 10px 30px rgba(0, 0, 0, 0.3);}/* 共享目標容器 */.shared-container {position: fixed;top: 20px;right: 20px;width: 300px;background: #2d3748;color: white;border-radius: 8px;padding: 15px;box-shadow: 0 5px 15px rgba(0, 0, 0, 0.3);z-index: 999;}.shared-item {background: rgba(255, 255, 255, 0.1);padding: 10px;margin: 8px 0;border-radius: 5px;font-size: 14px;}/* 延遲目標容器 */.deferred-target {margin-top: 20px;padding: 15px;background: #e6fffa;border: 2px solid #38b2ac;border-radius: 8px;min-height: 60px;}.deferred-content {background: #bee3f8;padding: 10px;border-radius: 5px;margin: 10px 0;}.status {display: inline-block;padding: 4px 8px;border-radius: 12px;font-size: 12px;margin-left: 10px;}.status.enabled {background: #c6f6d5;color: #22543d;}.status.disabled {background: #fed7d7;color: #742a2a;}.disabled-content {margin-top: 15px;padding: 15px;background: #fff3cd;border: 1px solid #ffc107;border-radius: 5px;}</style>
</head><body><div id="app"><div class="container"><h1>Vue 3 Teleport 特性演示</h1><!-- 1. 基礎 Teleport --><div class="demo-section"><h2>1. 基礎 Teleport</h2><p>將模態框傳送到 body 元素，脫離當前組件的 DOM 層級</p><div class="code-block"><Teleport to="body"><div v-if="showModal" class="modal-overlay"><div class="modal">模態框內容</div></div></Teleport></div><button class="btn" @click="showBasicModal = true">打開模態框</button></div><!-- 2. 禁用 Teleport --><div class="demo-section"><h2>2. 禁用 Teleport</h2><p>使用 <code>:disabled</code> 屬性控制是否啟用傳送功能</p><div class="code-block"><Teleport to="body" :disabled="isDisabled"><div v-if="showModal">內容</div></Teleport></div><button class="btn" @click="showDisabledModal = true">打開模態框</button><button class="btn" @click="isDisabled = !isDisabled">{{ isDisabled ? '啟用' : '禁用' }} Teleport</button><span class="status" :class="isDisabled ? 'disabled' : 'enabled'">{{ isDisabled ? '已禁用' : '已啟用' }}</span><!-- 禁用時顯示在原位置 --><div v-if="showDisabledModal && isDisabled" class="disabled-content"><h4>禁用狀態下的內容</h4><p>當 Teleport 被禁用時，內容會保留在原始位置而不是傳送到目標位置</p><button class="btn btn-danger" @click="showDisabledModal = false">關閉</button></div></div><!-- 3. 多個 Teleport 共享目標 --><div class="demo-section"><h2>3. 多個 Teleport 共享目標</h2><p>多個 Teleport 組件可以將內容掛載到同一個目標元素，內容會按順序追加</p><div class="code-block"><!-- 第一個 Teleport --><Teleport to="#modals"><div>A</div></Teleport><!-- 第二個 Teleport --><Teleport to="#modals"><div>B</div></Teleport></div><button class="btn" @click="showItemA = !showItemA">{{ showItemA ? '隱藏' : '顯示' }} 項目 A</button><button class="btn" @click="showItemB = !showItemB">{{ showItemB ? '隱藏' : '顯示' }} 項目 B</button><button class="btn" @click="showItemC = !showItemC">{{ showItemC ? '隱藏' : '顯示' }} 項目 C</button><p style="font-size: 14px; color: #666; margin-top: 10px;">查看右上角的共享容器，內容會按照掛載順序依次追加</p></div></div><!-- 基礎模態框 Teleport --><Teleport to="body"><div v-if="showBasicModal" class="modal-overlay" @click="showBasicModal = false"><div class="modal" @click.stop><h3 style="margin-bottom: 15px;">基礎 Teleport 模態框</h3><p>這個模態框被傳送到 body 元素，脫離了當前組件的 DOM 層級</p><button class="btn btn-danger" @click="showBasicModal = false">關閉</button></div></div></Teleport><!-- 可禁用的模態框 Teleport --><Teleport to="body" :disabled="isDisabled"><div v-if="showDisabledModal && !isDisabled" class="modal-overlay" @click="showDisabledModal = false"><div class="modal" @click.stop><h3 style="margin-bottom: 15px;">可禁用 Teleport 模態框</h3><p>當前 Teleport 狀態：{{ isDisabled ? '已禁用' : '已啟用' }}</p><button class="btn btn-danger" @click="showDisabledModal = false">關閉</button></div></div></Teleport><!-- 多個 Teleport 共享同一個目標 --><Teleport to="#shared-target"><div v-if="showItemA" class="shared-item"><strong>項目 A</strong> - 第一個 Teleport 組件的內容</div></Teleport><Teleport to="#shared-target"><div v-if="showItemB" class="shared-item"><strong>項目 B</strong> - 第二個 Teleport 組件的內容</div></Teleport><Teleport to="#shared-target"><div v-if="showItemC" class="shared-item"><strong>項目 C</strong> - 第三個 Teleport 組件的內容</div></Teleport></div><!-- 共享目標容器 (在 Vue 應用外部) --><div id="shared-target" class="shared-container"><h3 style="margin-bottom: 15px; text-align: center;">共享目標容器</h3><p style="font-size: 13px; opacity: 0.8; margin-bottom: 10px;">多個 Teleport 的內容會按掛載順序依次追加到這里</p></div><script>const { createApp, ref } = VuecreateApp({setup() {// 基礎模態框const showBasicModal = ref(false)// 可禁用的模態框const showDisabledModal = ref(false)const isDisabled = ref(false)// 共享目標項目const showItemA = ref(false)const showItemB = ref(false)const showItemC = ref(false)return {showBasicModal,showDisabledModal,isDisabled,showItemA,showItemB,showItemC,}}}).mount('#app')</script>
</body></html>
)
