跳到正文

Teleport 弹窗尺寸为什么会丢(6):Vue Vapor 模式下的新变化

Teleport 弹窗尺寸为什么会丢

  1. Teleport 怎样管理两个 DOM 位置
  2. Transition 怎样协调创建和移除
  3. CSS v-bind 怎样编译与更新变量
  4. 首次打开的变量漏填与修复
  5. CSS 变量回填的候选补丁与验证
  6. Vue Vapor 模式下的新变化(当前)

同一个弹窗,初始关闭,点击按钮只改 open。在 Vue 3.6.0-rc.14 上,普通组件首次打开时仍然会丢宽度,换成 Vapor 组件后,首次打开就能拿到 375px。只把弹窗内容换成 Vapor 组件,外层继续用普通 Teleport 和 Transition,宽度还是会丢。

三个例子最终都把元素放进 body。差异发生在内容从占位变成真实元素时,谁负责把最新的 CSS 变量写到新元素上。

三种写法,只切换一次 open

下面是普通组件的复现。过渡用 :css="false" 关闭 CSS 动画,让观察只涉及元素创建和变量写入。

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

const open = ref(false);
const width = ref('375px');
</script>

<template>
  <button @click="open = true">打开弹窗</button>
  <Teleport to="body">
    <Transition :css="false">
      <div v-if="open" class="panel">Panel</div>
    </Transition>
  </Teleport>
</template>

<style>
.panel {
  width: v-bind(width);
}
</style>

全 Vapor 的版本把 <script setup> 改为 <script setup vapor>,从 createVaporApp 启动。混合版本从 createApp 启动并安装 vaporInteropPlugin,保留上面的 Teleport、Transition 和样式,把弹窗元素放进 Vapor 的 DialogContent.vue,原来的 v-if 改挂到 <DialogContent v-if="open" /> 上。这样三组的 375px 仍由外层组件声明。

编译器和浏览器运行时均固定为 3.6.0-rc.14。在 Edge 中使用 1000px 宽的视口,保留 body 默认的 8px 边距,点击后读取面板的 inline style 和 getComputedStyle(panel).width。

组件组合 首次打开时面板上的 CSS 变量 计算宽度
普通 Teleport、Transition 和内容 缺失 984px
Vapor Teleport、Transition 和内容 已写入 375px 375px
普通 Teleport、Transition + Vapor 内容 缺失 984px

面板是块级元素。这个复现里的 width 取不到变量时会按 auto 计算,铺满 body 的 984px 可用宽度。不同布局中也可能表现为缩窄,所以排查时可以先看面板上的 CSS 变量,再看最终的像素值。

模板相同,运行时接手的对象变了

Vapor 是 Vue 3.6 的另一条渲染路径。对于这个弹窗,普通模板生成的渲染函数交给运行时一棵 VNode 树,Vapor 生成的代码则直接创建和更新 DOM。条件分支和插槽仍需保存会变化的内容,Vapor 用 fragment 来管理它们。

CSS 里的 v-bind(width) 在两种模式下都会编译成 var(--…)。SFC 编译器还会生成读取 width 的函数,把它交给运行时。切换到 Vapor 后,这个函数改交给 useVaporCssVars,模板中的 Teleport 和 Transition 也由 Vapor 运行时接管。

模板里的职责 普通组件 Vapor 组件
挂载到目标容器 Teleport 处理 VNode 子树,用锚点界定目标范围 VaporTeleport 用 TeleportFragment 管理目标位置和内容 block
协调条件切换与进入、离开 Transition 通过 BaseTransition 处理插槽返回的 VNode VaporTransition 把过渡钩子交给实际元素或会更新内容的 fragment
写入组件里的宽度 useCssVars 写组件根,再按 owner 标记找传送出去的元素 useVaporCssVars 直接向 block 中的节点写值,Teleport 的内容也可以直接交给它

这里的 block 可以是真实 DOM 节点,也可以是节点数组、组件实例或 fragment。拿到 fragment 时,可以沿着它的内容找到真正要写值的元素。条件分支还可以在下一批节点插入前触发钩子。

Vapor 在新分支插入前写入变量

弹窗关闭时,目标位置还没有面板。Vapor Teleport 初始化插槽时,会先把这段内容登记到声明 CSS 变量的组件上,供变量值变化时更新。随后 bindChildren() 调用这个组件的 applyCssVars(block),把刚拿到的 block 交给变量写入器。

useVaporCssVars 保存当前的变量值。它在 block 上找到元素就写值,找到会在之后换内容的条件分支,就登记插入前的钩子。弹窗首次打开时,条件分支创建面板,钩子拿着当下的 375px 写到这个新元素上,然后元素进入 DOM。这里没有改过 width,变量监听也无需重新触发。

普通 Teleport 则在自己的挂载或更新路径中调用 updateCssVars(),遍历锚点间的元素,先给它们补 data-v-owner,再调用 ctx.ut() 写值。首次挂载时没有面板,随后是内部的 Transition 更新了内容。外层 Teleport 没再走一遍标记路径,新元素也就不在 owner 查询结果里。

这里比较的是三种渲染路径,所以用同一个 Transition 弹窗。对于普通 VDOM,负责更新内容的也可以是第四篇里的 SlotOutlet。只要它创建的新根错过了 Teleport 的标记时机,变量就会漏写。

只把弹窗内容改成 Vapor,宽度仍由外层负责

混合写法里,DialogContent 负责渲染面板。声明 width、生成 CSS 变量名和安装变量写入器的仍是外层普通组件。普通 Teleport 会走 VNode 的更新路径,DialogContent 内部才切到 Vapor。这个子组件自己没有声明这条 CSS 变量,单独替换它也就没有给外层变量增加写入时机。

上游 #14594 补过 Vapor 路径中的 CSS 变量处理。对于仍由普通 Teleport 和普通组件负责变量的页面,首次打开漏写的现象在这版 RC 中依然可以复现。排查时可以先找到声明 v-bind() 的组件,再确认负责把内容传送出去的 Teleport 走的是哪条运行时路径。

3.5 和 3.6 的候选补丁怎样回填

3.5 的 #16237 和 3.6 的 #16238 沿用同一条回填路径。Teleport 先给锚点之间的元素补上 data-v-owner,再调用 ctx.ut() 写入变量。回填结束后,它才给可能独立换根的 VDOM 内容组件登记 onUpdated,记下当时的 DOM 根。

维护者关闭了这两份候选 PR,将修复指向使用 DOM 观察器的 #16239。第五篇对照了两种回填时机。先看 #16238 当时覆盖了哪些场景,再用同一个 3.6 基线验证观察器能否接手 Vapor 自己换根的情况。

内容组件更新后,钩子比较前后两次的 DOM 节点引用。比如 Transition 把注释占位换成面板,根变了,就安排 Teleport 再标记、再写值。只改了原元素的文字或属性时,根的引用没变,可以跳过回填。如果外层 Teleport 在同一轮更新中已经回填,登记时保存的根也会同步更新,子组件的钩子就能跳过额外的 owner 查询。

遇到 Vapor 实例时,用 vnode.el 比较节点

3.5 可以沿着内容组件的 subTree 往下找。3.6 的互操作层还会把 Vapor 实例放进 vnode.component。这种实例把渲染结果保存在 block 里。挂载时,互操作层先把自己的文本锚点放进 vnode.el,能解析到根元素时再把它换成该元素。

因此,3.6 的候选补丁走到 Vapor 实例就停下,用这个 VNode 已经暴露的 el 参与节点比较。真正回填时,Teleport 仍遍历自己的锚点范围。把 v-if 放在不同位置,就能看出这个处理的覆盖范围。

  • Transition 挂载 Vapor 子组件。v-if 在外层的 <DialogContent v-if="open" /> 上。打开时,VDOM 的 Transition 把注释占位换成 Vapor 子组件。Transition 的 onUpdated 能比较旧占位和新 VNode 的 el,触发回填。3.6 的回归测试覆盖了这条路径。
  • Vapor 子组件自己换根。外层一直渲染 <DialogContent />,只有组件内部的面板带 v-if。打开时,更新发生在 Vapor 的 block 里,外层 Transition 的 onUpdated 不会运行。#16238 的钩子覆盖不到这次换根。

Suspense 边界移到第三个参数

两版都通过 queuePostRenderEffect 安排回填,让它遵循 Suspense 的时机。若边界还有等待中的分支,回调先保存在 suspense.effects 里,等分支就绪再调度。3.6 的渲染后调度接口在回调和边界之间加入了任务 id,供渲染后队列排序。

-queuePostRenderEffect(state.update, instance.suspense)
+queuePostRenderEffect(state.update, undefined, instance.suspense)

回填沿用默认的队列顺序,所以第二个参数传 undefined,原先的 Suspense 边界放到第三个参数。

Vapor 子组件自己换根时的移植实测

#16239 于 2026 年 11 月 12 日合并到 main。下面的实验使用当时的 Vue 3.6 开发分支。为了单独验证 Vapor 换根,把 #16239 的 fbca6cf 实现移到本地 3.6 开发分支 819b15b。移植沿用 3.6 的变量读取和 Vapor 互操作,只把普通 Teleport 的锚点交给 useCssVars() 登记与观察。对照组与移植组使用同一份 3.6 编译器。

外层是 VDOM 组件,由 createApp 安装 vaporInteropPlugin 后挂载。它声明固定的 375px 宽度,模板只渲染 <Teleport to="body"><DialogContent /></Teleport>。最初 DialogContent 已经挂载,根元素是 <article>。点击按钮只改这个 Vapor 子组件里的 expanded,让它自己在 <article> 和 <section> 之间换根。两种根都用外层的 .panel { width: v-bind(width); }。

在 Microsoft Edge 中连续点击三次,确认每次都是新 DOM 节点,Vapor 子组件的 setup 只运行一次,外层组件的 onUpdated 一次也没运行。以下宽度取自 1000px 视口,保留 body 的默认边距。

运行时 首次挂载的 <article> 三次换根后的新元素
3.6 基线 819b15b 有 owner 标记,内联变量和计算宽度都是 375px 每次都缺少 owner 标记和内联变量,计算宽度都是 984px
同一基线移植 #16239 有 owner 标记,内联变量和计算宽度都是 375px 每次都补上 owner 标记和 375px 的内联变量,计算宽度都是 375px

首次挂载已经登记了 body 中的那段锚点范围。之后 Vapor 每换一次根,浏览器都会报告一个插在这个范围内的新元素,观察器随即补标记、写变量。这个实测覆盖的是普通 Teleport 内、已挂载的 Vapor 子组件独立换根的场景。两份 SFC、每次换根的变量值,以及锚点外插入节点时的查询次数见3.6 移植实测记录弹窗。

3.6 移植实测记录

打开原文件 teleport-vue36-observer-port-2026-11-12.json

{
  "engine": "Microsoft Edge 157.0.4341.46",
  "viewport": [
    1000,
    640
  ],
  "base": "819b15b98c01d24ec9549d81f75ade50076aa110",
  "upstreamPatch": "fbca6cf8ab4440abb718d4dcc4cd2bb1224f2926",
  "property": "--observer-width",
  "app": "<script setup>\nimport { onUpdated, ref } from 'vue'\nimport DialogContent from './DialogContent.vue'\nconst width = ref('375px')\nonUpdated(() => { window.ownerUpdates++ })\n</script>\n<template><Teleport to=\"body\"><DialogContent /></Teleport></template>\n<style>.panel { width: v-bind(width); }</style>",
  "child": "<script setup vapor>\nimport { ref } from 'vue'\nconst expanded = ref(false)\nwindow.childSetups++\n</script>\n<template>\n  <section v-if=\"expanded\" class=\"panel\"><button @click=\"expanded = false\">Switch root</button></section>\n  <article v-else class=\"panel\"><button @click=\"expanded = true\">Switch root</button></article>\n</template>",
  "observations": {
    "baseline": {
      "initial": {
        "tag": "ARTICLE",
        "owner": "0",
        "inline": "375px",
        "width": "375px",
        "inBody": true,
        "replaced": true,
        "ownerUpdates": 0,
        "childSetups": 1
      },
      "swaps": [
        {
          "tag": "SECTION",
          "owner": null,
          "inline": "",
          "width": "984px",
          "inBody": true,
          "replaced": true,
          "ownerUpdates": 0,
          "childSetups": 1
        },
        {
          "tag": "ARTICLE",
          "owner": null,
          "inline": "",
          "width": "984px",
          "inBody": true,
          "replaced": true,
          "ownerUpdates": 0,
          "childSetups": 1
        },
        {
          "tag": "SECTION",
          "owner": null,
          "inline": "",
          "width": "984px",
          "inBody": true,
          "replaced": true,
          "ownerUpdates": 0,
          "childSetups": 1
        }
      ],
      "unrelated": {
        "bodyCallbacks": 0,
        "ownerQueries": 0
      },
      "bundleSha256": "7b36d1f09dd30393baa27b4352c10f98667a64766f6243645f55e5ccdb456b00"
    },
    "observerPort": {
      "initial": {
        "tag": "ARTICLE",
        "owner": "0",
        "inline": "375px",
        "width": "375px",
        "inBody": true,
        "replaced": true,
        "ownerUpdates": 0,
        "childSetups": 1
      },
      "swaps": [
        {
          "tag": "SECTION",
          "owner": "0",
          "inline": "375px",
          "width": "375px",
          "inBody": true,
          "replaced": true,
          "ownerUpdates": 0,
          "childSetups": 1
        },
        {
          "tag": "ARTICLE",
          "owner": "0",
          "inline": "375px",
          "width": "375px",
          "inBody": true,
          "replaced": true,
          "ownerUpdates": 0,
          "childSetups": 1
        },
        {
          "tag": "SECTION",
          "owner": "0",
          "inline": "375px",
          "width": "375px",
          "inBody": true,
          "replaced": true,
          "ownerUpdates": 0,
          "childSetups": 1
        }
      ],
      "unrelated": {
        "bodyCallbacks": 1,
        "ownerQueries": 0
      },
      "bundleSha256": "b132592214f05c14ab680b4ceebe041bd4d5eba7bbd63cea10586a6324912146"
    }
  }
}