6.2 Teleport：穿梭于任意 DOM 节点的传送门

Teleport 是 Vue 3 中一个强大的内置组件，它能够将组件的内容渲染到 DOM 树中的任意位置，而不受组件层级结构的限制。这种能力在构建模态框、通知系统、全屏组件等场景中极其有用。本节将深入分析 Teleport 的源码实现，探索其背后的传送门机制。

核心概念与设计理念

基本概念

Teleport 组件解决了一个常见的 UI 开发问题：如何将组件内容渲染到组件层级之外的 DOM 位置。传统的组件渲染受限于父子关系，而 Teleport 打破了这种限制，提供了一种"传送门"机制。

typescript

// core/packages/runtime-core/src/components/Teleport.ts
export interface TeleportProps {
  to: string | RendererElement | null | undefined
  disabled?: boolean
  defer?: boolean
}

export type TeleportVNode = VNode<RendererNode, RendererElement, TeleportProps>

核心属性解析

to 属性：指定传送的目标位置，可以是 CSS 选择器字符串或 DOM 元素引用。

disabled 属性：控制传送功能的启用状态，当为 true 时，内容将在原位置渲染。

defer 属性：延迟传送操作，在组件挂载后再执行传送。

目标解析与选择机制

目标解析函数

typescript

const resolveTarget = <T = RendererElement>(
  props: TeleportProps | null,
  select: RendererOptions['querySelector'],
): T | null => {
  const targetSelector = props && props.to
  if (isString(targetSelector)) {
    if (!select) {
      __DEV__ &&
        warn(
          `Current renderer does not support string target for Teleports. ` +
            `(missing querySelector renderer option)`,
        )
      return null
    } else {
      const target = select(targetSelector)
      if (__DEV__ && !target && !isTeleportDisabled(props)) {
        warn(
          `Failed to locate Teleport target with selector "${targetSelector}". ` +
            `Note the target element must exist before the component is mounted - ` +
            `i.e. the target cannot be rendered by the component itself, and ` +
            `ideally should be outside of the entire Vue component tree.`,
        )
      }
      return target as T
    }
  } else {
    if (__DEV__ && !targetSelector && !isTeleportDisabled(props)) {
      warn(`Invalid Teleport target: ${targetSelector}`)
    }
    return targetSelector as T
  }
}

这个函数负责将 to 属性转换为实际的 DOM 元素：

字符串选择器处理：使用 querySelector 查找目标元素
元素引用处理：直接返回传入的 DOM 元素
错误处理：在开发模式下提供详细的错误信息
安全检查：确保目标元素在组件挂载前已存在

命名空间检测

typescript

const isTargetSVG = (target: RendererElement): boolean =>
  typeof SVGElement !== 'undefined' && target instanceof SVGElement

const isTargetMathML = (target: RendererElement): boolean =>
  typeof MathMLElement === 'function' && target instanceof MathMLElement

Teleport 能够智能检测目标容器的命名空间，确保在 SVG 或 MathML 容器中正确渲染内容。

核心处理流程

TeleportImpl 组件实现

typescript

export const TeleportImpl = {
  name: 'Teleport',
  __isTeleport: true,
  process(
    n1: TeleportVNode | null,
    n2: TeleportVNode,
    container: RendererElement,
    anchor: RendererNode | null,
    parentComponent: ComponentInternalInstance | null,
    parentSuspense: SuspenseBoundary | null,
    namespace: ElementNamespace,
    slotScopeIds: string[] | null,
    optimized: boolean,
    internals: RendererInternals,
  ): void
}

挂载阶段处理

当 Teleport 首次挂载时（n1 == null），执行以下步骤：

typescript

if (n1 == null) {
  // 1. 创建占位符锚点
  const placeholder = (n2.el = __DEV__
    ? createComment('teleport start')
    : createText(''))
  const mainAnchor = (n2.anchor = __DEV__
    ? createComment('teleport end')
    : createText(''))
  insert(placeholder, container, anchor)
  insert(mainAnchor, container, anchor)

  // 2. 定义挂载函数
  const mount = (container: RendererElement, anchor: RendererNode) => {
    if (shapeFlag & ShapeFlags.ARRAY_CHILDREN) {
      if (parentComponent && parentComponent.isCE) {
        parentComponent.ce!._teleportTarget = container
      }
      mountChildren(
        children as VNodeArrayChildren,
        container,
        anchor,
        parentComponent,
        parentSuspense,
        namespace,
        slotScopeIds,
        optimized,
      )
    }
  }

  // 3. 目标挂载逻辑
  const mountToTarget = () => {
    const target = (n2.target = resolveTarget(n2.props, querySelector))
    const targetAnchor = prepareAnchor(target, n2, createText, insert)
    if (target) {
      // 命名空间检测
      if (namespace !== 'svg' && isTargetSVG(target)) {
        namespace = 'svg'
      } else if (namespace !== 'mathml' && isTargetMathML(target)) {
        namespace = 'mathml'
      }
      if (!disabled) {
        mount(target, targetAnchor)
        updateCssVars(n2, false)
      }
    }
  }
}

关键步骤解析：

占位符创建：在原位置创建开始和结束锚点，保持组件在虚拟 DOM 树中的位置
挂载函数定义：封装子组件的挂载逻辑，支持在不同容器中复用
目标解析：解析传送目标并处理命名空间
条件挂载：根据 disabled 状态决定挂载位置

延迟传送机制

typescript

if (disabled) {
  mount(container, mainAnchor)
  updateCssVars(n2, true)
}

if (isTeleportDeferred(n2.props)) {
  n2.el!.__isMounted = false
  queuePostRenderEffect(() => {
    mountToTarget()
    delete n2.el!.__isMounted
  }, parentSuspense)
} else {
  mountToTarget()
}

延迟传送确保目标元素在传送执行前已经存在，这对于动态创建的目标容器特别重要。

更新阶段处理

状态变更检测

typescript

// 更新阶段的核心逻辑
const wasDisabled = isTeleportDisabled(n1.props)
const currentContainer = wasDisabled ? container : target
const currentAnchor = wasDisabled ? mainAnchor : targetAnchor

// 子组件更新
if (dynamicChildren) {
  patchBlockChildren(
    n1.dynamicChildren!,
    dynamicChildren,
    currentContainer,
    parentComponent,
    parentSuspense,
    namespace,
    slotScopeIds,
  )
  traverseStaticChildren(n1, n2, !__DEV__)
} else if (!optimized) {
  patchChildren(
    n1,
    n2,
    currentContainer,
    currentAnchor,
    parentComponent,
    parentSuspense,
    namespace,
    slotScopeIds,
    false,
  )
}

状态切换处理

typescript

if (disabled) {
  if (!wasDisabled) {
    // enabled -> disabled: 移回原位置
    moveTeleport(
      n2,
      container,
      mainAnchor,
      internals,
      TeleportMoveTypes.TOGGLE,
    )
  }
} else {
  // 目标变更检测
  if ((n2.props && n2.props.to) !== (n1.props && n1.props.to)) {
    const nextTarget = (n2.target = resolveTarget(n2.props, querySelector))
    if (nextTarget) {
      moveTeleport(
        n2,
        nextTarget,
        null,
        internals,
        TeleportMoveTypes.TARGET_CHANGE,
      )
    }
  } else if (wasDisabled) {
    // disabled -> enabled: 移到目标位置
    moveTeleport(
      n2,
      target,
      targetAnchor,
      internals,
      TeleportMoveTypes.TOGGLE,
    )
  }
}

移动策略与算法

TeleportMoveTypes 枚举

typescript

export enum TeleportMoveTypes {
  TARGET_CHANGE,  // 目标变更
  TOGGLE,         // 启用/禁用切换
  REORDER,        // 重新排序
}

moveTeleport 函数实现

typescript

function moveTeleport(
  vnode: VNode,
  container: RendererElement,
  parentAnchor: RendererNode | null,
  { o: { insert }, m: move }: RendererInternals,
  moveType: TeleportMoveTypes = TeleportMoveTypes.REORDER,
): void {
  // 目标变更时移动目标锚点
  if (moveType === TeleportMoveTypes.TARGET_CHANGE) {
    insert(vnode.targetAnchor!, container, parentAnchor)
  }
  
  const { el, anchor, shapeFlag, children, props } = vnode
  const isReorder = moveType === TeleportMoveTypes.REORDER
  
  // 重排序时移动主视图锚点
  if (isReorder) {
    insert(el!, container, parentAnchor)
  }
  
  // 移动子节点的条件判断
  if (!isReorder || isTeleportDisabled(props)) {
    if (shapeFlag & ShapeFlags.ARRAY_CHILDREN) {
      for (let i = 0; i < (children as VNode[]).length; i++) {
        move(
          (children as VNode[])[i],
          container,
          parentAnchor,
          MoveType.REORDER,
        )
      }
    }
  }
  
  if (isReorder) {
    insert(anchor!, container, parentAnchor)
  }
}

移动策略分析：

TARGET_CHANGE：仅移动目标锚点，子内容跟随
TOGGLE：在原位置和目标位置间切换
REORDER：处理组件树重排序时的位置调整

锚点管理机制

prepareAnchor 函数

typescript

function prepareAnchor(
  target: RendererElement | null,
  vnode: TeleportVNode,
  createText: RendererOptions['createText'],
  insert: RendererOptions['insert'],
) {
  const targetStart = (vnode.targetStart = createText(''))
  const targetAnchor = (vnode.targetAnchor = createText(''))

  // 特殊属性标记，用于渲染器的 nextSibling 搜索优化
  targetStart[TeleportEndKey] = targetAnchor

  if (target) {
    insert(targetStart, target)
    insert(targetAnchor, target)
  }

  return targetAnchor
}

锚点系统确保：

位置标记：在目标容器中标记 Teleport 内容的边界
搜索优化：通过 TeleportEndKey 优化渲染器的节点遍历
移动支持：为内容移动提供稳定的参考点

清理与卸载机制

remove 方法实现

typescript

remove(
  vnode: VNode,
  parentComponent: ComponentInternalInstance | null,
  parentSuspense: SuspenseBoundary | null,
  { um: unmount, o: { remove: hostRemove } }: RendererInternals,
  doRemove: boolean,
): void {
  const {
    shapeFlag,
    children,
    anchor,
    targetStart,
    targetAnchor,
    target,
    props,
  } = vnode

  // 清理目标位置的锚点
  if (target) {
    hostRemove(targetStart!)
    hostRemove(targetAnchor!)
  }

  // 清理原位置的锚点
  doRemove && hostRemove(anchor!)
  
  // 卸载子组件
  if (shapeFlag & ShapeFlags.ARRAY_CHILDREN) {
    const shouldRemove = doRemove || !isTeleportDisabled(props)
    for (let i = 0; i < (children as VNode[]).length; i++) {
      const child = (children as VNode[])[i]
      unmount(
        child,
        parentComponent,
        parentSuspense,
        shouldRemove,
        !!child.dynamicChildren,
      )
    }
  }
}

CSS 变量与样式处理

updateCssVars 函数

typescript

function updateCssVars(vnode: VNode, isDisabled: boolean) {
  const ctx = vnode.ctx
  if (ctx && ctx.ut) {
    let node, anchor
    if (isDisabled) {
      node = vnode.el
      anchor = vnode.anchor
    } else {
      node = vnode.targetStart
      anchor = vnode.targetAnchor
    }
    while (node && node !== anchor) {
      if (node.nodeType === 1) node.setAttribute('data-v-owner', ctx.uid)
      node = node.nextSibling
    }
    ctx.ut()
  }
}

这个函数确保 CSS 变量在传送后仍能正确工作，通过设置 data-v-owner 属性维护样式作用域。

实际应用场景

模态框实现

vue

<template>
  <div class="modal-trigger">
    <button @click="showModal = true">打开模态框</button>
    
    <Teleport to="body">
      <div v-if="showModal" class="modal-overlay" @click="showModal = false">
        <div class="modal-content" @click.stop>
          <h2>模态框标题</h2>
          <p>模态框内容</p>
          <button @click="showModal = false">关闭</button>
        </div>
      </div>
    </Teleport>
  </div>
</template>

通知系统

vue

<template>
  <Teleport to="#notification-container">
    <div v-for="notification in notifications" 
         :key="notification.id" 
         class="notification">
      {{ notification.message }}
    </div>
  </Teleport>
</template>

条件传送

vue

<template>
  <Teleport :to="isMobile ? 'body' : '.desktop-container'" :disabled="!shouldTeleport">
    <div class="responsive-content">
      <!-- 内容根据设备类型传送到不同位置 -->
    </div>
  </Teleport>
</template>

性能优化策略

1. 目标缓存

javascript

// 缓存目标元素引用，避免重复查询
const targetCache = new Map()

function getCachedTarget(selector) {
  if (!targetCache.has(selector)) {
    targetCache.set(selector, document.querySelector(selector))
  }
  return targetCache.get(selector)
}

2. 延迟传送优化

javascript

// 使用 defer 属性优化初始渲染性能
<Teleport to="#heavy-container" defer>
  <ExpensiveComponent />
</Teleport>

3. 条件渲染结合

javascript

// 结合 v-if 避免不必要的传送操作
<Teleport to="body" v-if="shouldRender">
  <ModalContent />
</Teleport>

调试与开发工具

开发模式增强

在开发模式下，Teleport 提供了丰富的调试信息：

详细的警告信息：目标元素不存在时的具体提示
可视化锚点：使用注释节点标记传送边界
HMR 支持：热更新时强制完整 diff

Vue DevTools 集成

Teleport 组件在 Vue DevTools 中有特殊的显示方式，能够清晰展示传送关系和目标位置。

最佳实践总结

1. 目标元素管理

确保目标元素在 Teleport 挂载前存在
使用稳定的选择器或元素引用
避免传送到会被动态移除的容器

2. 性能考虑

合理使用 defer 属性延迟非关键传送
结合条件渲染减少不必要的 DOM 操作
缓存目标元素引用避免重复查询

3. 样式处理

注意传送后的样式作用域问题
使用全局样式或 CSS-in-JS 处理传送内容
考虑目标容器的 z-index 层级

4. 可访问性

保持逻辑焦点管理
确保屏幕阅读器能正确理解内容结构
处理键盘导航的连续性

Teleport 组件通过精巧的设计和实现，为 Vue 3 应用提供了强大的 DOM 传送能力。其源码展现了现代前端框架在处理复杂 UI 需求时的技术深度和设计智慧，为开发者构建灵活的用户界面提供了坚实的技术基础。

6.2 Teleport：穿梭于任意 DOM 节点的传送门 ​

核心概念与设计理念 ​

基本概念 ​

核心属性解析 ​

目标解析与选择机制 ​

目标解析函数 ​

命名空间检测 ​

核心处理流程 ​

TeleportImpl 组件实现 ​

挂载阶段处理 ​

延迟传送机制 ​

更新阶段处理 ​

状态变更检测 ​

状态切换处理 ​

移动策略与算法 ​

TeleportMoveTypes 枚举 ​

moveTeleport 函数实现 ​

锚点管理机制 ​

prepareAnchor 函数 ​

清理与卸载机制 ​

remove 方法实现 ​

CSS 变量与样式处理 ​

updateCssVars 函数 ​

实际应用场景 ​

模态框实现 ​

通知系统 ​

条件传送 ​

性能优化策略 ​

1. 目标缓存 ​

2. 延迟传送优化 ​

3. 条件渲染结合 ​

调试与开发工具 ​

开发模式增强 ​

Vue DevTools 集成 ​

最佳实践总结 ​

1. 目标元素管理 ​

2. 性能考虑 ​

3. 样式处理 ​

4. 可访问性 ​

6.2 Teleport：穿梭于任意 DOM 节点的传送门

核心概念与设计理念

基本概念

核心属性解析

目标解析与选择机制

目标解析函数

命名空间检测

核心处理流程

TeleportImpl 组件实现

挂载阶段处理

延迟传送机制

更新阶段处理

状态变更检测

状态切换处理

移动策略与算法

TeleportMoveTypes 枚举

moveTeleport 函数实现

锚点管理机制

prepareAnchor 函数

清理与卸载机制

remove 方法实现

CSS 变量与样式处理

updateCssVars 函数

实际应用场景

模态框实现

通知系统

条件传送

性能优化策略

1. 目标缓存

2. 延迟传送优化

3. 条件渲染结合

调试与开发工具

开发模式增强

Vue DevTools 集成

最佳实践总结

1. 目标元素管理

2. 性能考虑

3. 样式处理

4. 可访问性