uni-app小程序新增Teleport功能支持

前言

搞 Vue 开发的朋友都知道，写弹窗、抽屉、Toast、ActionSheet 这类组件时，teleport 几乎是标配。它能直接把内容丢到当前组件层级之外，避免被父级 overflow、z-index 或者样式隔离给搞出各种莫名其妙的 bug。

但小程序不是浏览器，没有真正的 document.body，更没法像 Web 那样随意挪动 DOM 节点。所以以前做跨端组件时，免不了要写这种条件编译的代码：

 复制代码
<teleport to="body">
  <popup />
teleport>

<root-portal>
  <popup />
root-portal>

好在从 5.14 版本开始，小程序端终于可以直接写 teleport 了。也就是说，以后 H5 和小程序不用再两套条件编译，统一走 Vue 的写法就行：

 复制代码<teleport to="body">
  <popup />
teleport>

在 H5 端，它依然是 Vue 原生的 teleport；而在支持的小程序端，uni-app 会自动把它转成平台原生的 root-portal。

支持平台

目前支持的有这几个：微信小程序、支付宝小程序、京东小程序。够用，但不算全覆盖——后续会不会继续扩展，可以保持关注。

使用方式

用法和 Vue 完全一致，没有任何新概念需要学习。简单直接：

 复制代码<template>
  <view class="page">
    <button @click="show = true">打开弹窗button>    <teleport to="body">
      <view v-if="show" class="mask" @click="show = false">
        <view class="dialog" @click.stop>
          我是弹窗内容
        view>
      view>
    teleport>
  view>
template><script setup>
import { ref } from 'vue'const show = ref(false)
script>

编译到支持的小程序平台后，模板会变成这样：

 复制代码<root-portal>
  <view class="mask">
    <view class="dialog">
      我是弹窗内容
    view>
  view>
root-portal>

直观感受就是：开发者写的是 teleport，小程序真正跑起来的是 root-portal。

实现原理

这里的本质是编译期转换。uni-app 在小程序编译阶段会识别模板中的 teleport 标签，然后把它替换成 root-portal。既能保留 Vue 的开发体验，又能利用小程序平台已有的原生能力。

整体流程可以理解为：

 复制代码<teleport to="body">
  <view />
teleport>

编译为：

 复制代码<root-portal>
  <view />
root-portal>

需要说明的是，小程序的 root-portal 和 Vue 的 teleport 并不是完全等价。Vue 的 teleport 可以通过 to 指定目标节点，而小程序的 root-portal 只是把内容提升到页面根节点下渲染，并不支持传送到任意位置。所以 uni-app 做的是能力映射，而不是在小程序里完整模拟 Web Teleport。

属性差异

虽然写法统一成了 teleport，但小程序端最终落到 root-portal 头上，部分属性自然会有差异。下面逐个说说。

to 和 defer

to 和 defer 都是 Vue Teleport 规范的属性，但小程序 root-portal 没有对应能力，编译到小程序端时会被直接移除。

 复制代码<teleport to="body" defer>
  <popup />
teleport>

会被转换成类似：

 复制代码<root-portal>
  <popup />
root-portal>

如果代码同时要跑 H5 和小程序，可以继续保留这些属性：to="body" 和 defer 在 H5 端依然有意义，只是在小程序端不生效而已，不会报错。

disabled

Vue Teleport 用 disabled 控制是否禁用传送：

 复制代码<teleport :disabled="disabled">
  <popup />
teleport>

而小程序 root-portal 使用的是 enable，语义正好相反。因此编译到小程序时，uni-app 会自动做一次取反转换。例如：

 复制代码<teleport :disabled="disabled">
  <popup />
teleport>

会被处理成：

 复制代码<root-portal :enable="!disabled">
  <popup />
root-portal>

开发者照着 Vue 的 disabled 语义写就行，不需要手动改成 enable。省心不少。