跳到正文

我所理解的 Vue 最佳实践(5):用模板 ref 连接 Teleport 挂载点

我所理解的 Vue 最佳实践

  1. Vue watch 的 cleanup 到底清理了什么
  2. Vue 的 script setup 泛型组件到底解决了什么
  3. defineModel 已经声明了什么:避免重复 v-model 契约和默认值分叉
  4. 用插槽选择器 slotted 给传入内容设样式
  5. 用模板 ref 连接 Teleport 挂载点(当前)
  6. 保留 click 写法,让按钮自动防连点和 loading

阅读器的撤销、重做和切换对比基线都作用于当前文档,按钮却出现在窗口顶部工具栏的「更多」菜单中。Teleport 可以把这些按钮渲染到菜单里,props 和事件仍沿原来的组件关系传递。工具栏提供菜单的位置,阅读区根据当前标签和审阅视图决定要不要提供操作。

用 to="#review-menu" 时,阅读区知道工具栏里某个节点的 ID,工具栏的接口上却看不到谁在使用它。改名需要同时记得修改两处。即使把 ID 提成共享常量,工具栏进入设置页、卸载文档操作区时,也得另外判断这个节点是否存在。我更愿意把实际挂载的节点写进组件接口。

工具栏暴露节点,页面负责接线

以审阅菜单为例,工具栏用 useTemplateRef() 记录挂载点,再用 defineExpose() 将它作为具名接口。useTemplateRef() 从 Vue 3.5 起可用。通过组件实例访问暴露的 ref 时,Vue 会解包它。

<!-- WorkbenchToolbar.vue -->
<script setup lang="ts">
import { useTemplateRef } from 'vue';

const reviewMenuTarget = useTemplateRef<HTMLDivElement>('review-menu-target');

defineExpose({ reviewMenuTarget });
</script>

<template>
  <div ref="review-menu-target"></div>
</template>

页面同时渲染工具栏和阅读区。它从工具栏实例读取 reviewMenuTarget,并通过同名 prop 传给阅读区。在页面找到 :review-menu-target="reviewMenuTarget",就能沿绑定看到提供者。

<!-- App.vue -->
<script setup lang="ts">
import { computed, useTemplateRef } from 'vue';
import ReadingPane from './ReadingPane.vue';
import WorkbenchToolbar from './WorkbenchToolbar.vue';

const toolbar = useTemplateRef<InstanceType<typeof WorkbenchToolbar>>('toolbar');
const reviewMenuTarget = computed(() => toolbar.value?.reviewMenuTarget ?? null);
</script>

<template>
  <workbench-toolbar ref="toolbar" />
  <reading-pane :review-menu-target="reviewMenuTarget" />
</template>

节点就绪后再挂载 Teleport

阅读区收到的目标类型是 HTMLElement | null。首次渲染时可能还没有节点,节点卸载后模板 ref 也会清空。把节点是否存在写进原有的渲染条件,工具栏重建时就会使用新节点。这里的 active 和 markedView 仍然负责选择当前标签的审阅操作。

<template>
  <teleport v-if="active && markedView && reviewMenuTarget" :to="reviewMenuTarget">
    <review-actions />
  </teleport>
</template>

这也说明了 defer 的适用范围。它把目标解析推迟到当前挂载或更新周期的后段,目标在之后的周期才出现时仍需要等待条件成立。用模板 ref 表达节点是否就绪,可以直接覆盖工具栏随页面切换而移除、重新挂载的情况。

文档提供的固定容器可以使用选择器

全局弹层直接挂到 body,或者宿主 HTML 为多处浮层提供固定容器时,选择器本身就是文档接口。组件负责创建的容器则优先公开节点引用,尤其是受 v-if 控制的工具栏、面板和弹窗。

可以用 @sheng/vue-prefer-teleport-target-ref 提示这类写法。它检查模板里可静态求值的选择器,覆盖直接写在 to 上的字符串和同文件常量。body 默认允许,项目可以通过 allowedSelectors 补充宿主提供的固定容器。

传送内容的动态样式

固定颜色、间距和边框可以用 class 和样式块表达。@sheng/ui-no-inline-style 检查字面 style 和可静态求值的固定绑定。例如 :style="{ color: 'red' }" 可以改成一个类名。

多个审阅按钮共用同一个组件状态时,可以在样式块通过 CSS v-bind() 引用它,例如 color: v-bind(accent)。样式块能访问组件的 props、ref 和 computed。循环项 item 和作用域插槽提供的 row 只在各自的模板作用域中可见,可以用 :style="{ color: row.color }" 把逐项计算的值直接交给元素。参见 Vue 的单文件组件样式文档。

传送内容还要核对 CSS 变量是否写到了实际节点。旧版 Vue 中,传送内容的子组件独立换根时,新节点可能缺少动态样式所需的 CSS 变量。Vue #16239 已合并到 main。项目若锁定在受影响的版本,可以用 :style 把动态值或自定义属性写到真实节点上。验证时检查弹层首次打开和子组件换根后的实际样式。回填路径及 3.6 的本地实验见《CSS 变量回填的候选补丁与验证》和《Vue Vapor 模式下的新变化》。