Vue3组合式函数结合Teleport渲染组件失效问题排查与解决

核心问题 #

你写的代码无法运行，不是Teleport的用法错误，而是犯了一个关键错误：h()函数仅创建虚拟DOM节点（VNode），并没有将其挂载到真实DOM中，所以弹窗组件根本不会被渲染。此外，代码也没有处理弹窗关闭后的组件卸载逻辑，即使后续挂载成功，也会造成内存泄漏。

可行解决办法 #

要实现编程式弹窗，需要完成「创建VNode → 挂载到真实DOM → 关闭时卸载组件」的完整流程，以下是两种可靠的实现方式：

方式一：使用render函数挂载 #

import { h, render, Teleport } from 'vue'
import BaseModal from '@shared/components/BaseModal.vue'

export default function useModal({ to = 'body' } = {}) {
  const show = (props = {}, slots = {}) => {
    // 创建临时容器用于挂载组件
    const container = document.createElement('div')

    // 定义关闭后的清理逻辑
    const handleClose = () => {
      // 卸载组件
      render(null, container)
      // 移除DOM元素
      document.body.removeChild(container)
    }

    // 合并传入的props，添加关闭回调（需和BaseModal的关闭事件对应）
    const modalProps = {
      ...props,
      onClose: handleClose
    }

    // 创建包含Teleport的VNode
    const vnode = h(Teleport, { to }, [
      h(BaseModal, modalProps, slots)
    ])

    // 挂载VNode到容器，再将容器内容添加到目标节点
    render(vnode, container)
    document.body.appendChild(container.firstElementChild)
  }

  return { show }
}

方式二：使用createApp挂载 #

如果需要更完整的组件上下文（比如使用全局插件），可以用createApp方式：

import { createApp, h, Teleport } from 'vue'
import BaseModal from '@shared/components/BaseModal.vue'

export default function useModal({ to = 'body' } = {}) {
  const show = (props = {}, slots = {}) => {
    const container = document.createElement('div')
    let appInstance = null

    const handleClose = () => {
      // 卸载整个应用实例
      appInstance.unmount()
      document.body.removeChild(container)
    }

    const modalProps = {
      ...props,
      onClose: handleClose
    }

    // 创建应用实例并挂载
    appInstance = createApp({
      render() {
        return h(Teleport, { to }, h(BaseModal, modalProps, slots))
      }
    })

    appInstance.mount(container)
    document.body.appendChild(container.firstElementChild)
  }

  return { show }
}

关键注意点 #

• 确保BaseModal组件的关闭事件是onClose（如果你的组件用@close触发，Vue会自动映射为onClose），如果事件名不同，需要对应修改modalProps中的回调键名。
• 每次调用show都会创建新的组件实例和DOM元素，关闭时必须执行卸载和清理，避免内存泄漏。
• Teleport的用法是正确的，它的作用是将内部组件渲染到指定的to目标节点中，只要配合正确的挂载流程就能正常工作。

内容的提问来源于stack exchange，提问作者Riza Khan