Vue shallowRef 管理第三方实例的响应式边界

在 Vue 3 里保存图表、地图、编辑器、播放器等第三方实例，我更倾向于用 shallowRef，而不是普通 ref 或把实例塞进 reactive。原因很直接：这类对象由第三方库维护方法、内部缓存、DOM 引用和对象身份，Vue 通常只需要知道“实例现在是哪个”，不需要把整个对象树变成深度响应式。

shallowRef 的边界停在 .value：读取和替换 instanceRef.value 是响应式的，实例内部属性保持原样。官方文档也把它定位为大型数据结构性能优化和外部状态系统集成的工具。对第三方类实例来说，这个语义往往正合适。

Vue 官方文档：https://vuejs.org/api/reactivity-advanced.html#shallowref

我为什么不再把第三方实例放进普通 ref

第一次封装大型可视化组件时，最自然的写法通常是 const chart = ref(null)，挂载后再把实例赋进去。功能可能照常工作，但普通 ref 会对对象值做深层响应式转换。对于由外部库维护的复杂实例，这层代理通常没有业务价值，还可能让对象身份、私有字段、原型方法或库内部缓存变得更难推理。

这里不必把问题描述成“普通 ref 一定会让第三方库报错”。真正稳定的判断信号是：模板是否需要响应实例的嵌套字段？如果不需要，深度转换就是多余的。把实例视为一个可替换的句柄，边界会更清楚。

把响应式边界停在 .value

下面用一个通用的 ExternalWidget 接口表示第三方实例。重点不在具体库，而在引用语义：实例内部由 SDK 自己修改，Vue 只跟踪根引用。

import { shallowRef, watchEffect } from 'vue'

interface ExternalWidget {
  setData(data: unknown[]): void
  resize(): void
  destroy(): void
  readonly internalState: object
}

// 第三方实例保持原样，只有 .value 的读取与替换参与依赖追踪。
const instanceRef = shallowRef(null)

watchEffect(() => {
  // effect 依赖的是根引用是否存在，不会深度订阅 internalState。
  const ready = instanceRef.value !== null
  console.info('widget ready:', ready)
})

function replaceInstance(next: ExternalWidget) {
  // 替换根引用会通知依赖 instanceRef.value 的 effect。
  instanceRef.value = next
}

如果执行 instanceRef.value.internalState 内部的某个深层变更，Vue 不会因此自动重新运行依赖。它不是缺陷，而是这条边界的核心：外部对象按自身机制变化，Vue 视图只订阅团队明确选择的状态。

把创建、调用与销毁写进同一个 composable

我更喜欢把实例生命周期收进一个 composable，而不是让页面组件到处访问实例。这样容器、创建工厂、公开方法和清理动作都在一个边界内，组件只拿到它真正需要的入口。

import {
  onBeforeUnmount,
  onMounted,
  ref,
  shallowRef,
  type Ref
} from 'vue'

interface ExternalWidget {
  setData(data: unknown[]): void
  resize(): void
  destroy(): void
}

type WidgetFactory = (host: HTMLElement) => ExternalWidget

export function useExternalWidget(createWidget: WidgetFactory) {
  const hostRef: Ref = ref(null)
  const instanceRef = shallowRef(null)
  const isReady = ref(false)

  onMounted(() => {
    if (!hostRef.value) return

    // 创建动作只发生在容器可用之后，实例用浅层引用持有。
    instanceRef.value = createWidget(hostRef.value)
    isReady.value = true
  })

  function updateData(data: unknown[]) {
    // 对外只暴露业务动作，不让组件直接修改实例内部字段。
    instanceRef.value?.setData(data)
  }

  function resize() {
    instanceRef.value?.resize()
  }

  onBeforeUnmount(() => {
    // 先调用第三方销毁方法，再清空根引用，避免遗留 DOM 绑定与监听器。
    instanceRef.value?.destroy()
    instanceRef.value = null
    isReady.value = false
  })

  return { hostRef, instanceRef, isReady, updateData, resize }
}

组件模板只需把容器绑定给 hostRef，业务数据变化时调用 updateData。如果库还注册了窗口监听、观察器或事件总线，优先使用库公开的销毁 API；不能确认清理内容时，不要假设把引用设为 null 就等于释放所有外部资源。

第三方对象变了，界面怎么更新

shallowRef 不会追踪内部变化，因此要先问：界面真正需要什么？大多数场景只需显示少量状态，例如是否就绪、当前选中数量、缩放级别或错误信息。更稳妥的做法是把这些值同步到普通 ref，而不是让模板读取第三方实例深层字段。

import { ref, shallowRef } from 'vue'

interface ExternalWidget {
  on(event: 'selection-change', listener: (ids: string[]) => void): void
  off(event: 'selection-change', listener: (ids: string[]) => void): void
}

const instanceRef = shallowRef(null)
const selectedCount = ref(0)

// 把 UI 真正关心的派生值镜像为普通 ref，而不是深度观察整个实例。
const handleSelection = (ids: string[]) => {
  selectedCount.value = ids.length
}

function bindSelection(instance: ExternalWidget) {
  instance.on('selection-change', handleSelection)
}

function unbindSelection(instance: ExternalWidget) {
  // 使用同一个函数引用解绑，避免组件卸载后继续收到外部事件。
  instance.off('selection-change', handleSelection)
}

这种写法把“第三方事件”和“Vue 展示状态”连接起来，状态来源清楚，也更容易测试。对我来说，这比在实例内部找一个字段直接渲染更可控。

什么时候才需要 triggerRef

官方的 triggerRef 用于强制触发依赖某个 shallow ref 的 effect，典型场景是你确实对内部对象做了深层修改，又明确希望相关 effect 重新运行。它不是每次调用第三方方法后的固定补丁。

import { shallowRef, triggerRef, watchEffect } from 'vue'

const stateRef = shallowRef({ selectedIds: [] as string[] })

watchEffect(() => {
  // effect 读取根引用，但深层 push 本身不会触发它。
  console.info('selected:', stateRef.value.selectedIds.length)
})

function appendSelection(id: string) {
  stateRef.value.selectedIds.push(id)

  // 只有确认需要让依赖重新计算时，才显式通知。
  triggerRef(stateRef)
}

如果这类显式通知频繁出现，通常说明状态设计可以再拆分：把 selectedIds 本身放进普通 ref，或每次用新对象替换 stateRef.value。对于纯第三方实例，优先用 SDK 事件同步少量 UI 状态，而不是对实例句柄反复 triggerRef。

shallowRef、markRaw 和普通 ref 怎么选

shallowRef 是“容器浅，值保持原样”；markRaw 是给对象本身打上永不转换为代理的标记；普通 ref 则适合希望对象内部也参与响应式的状态。它们不是相互替代的语法糖。

Vue 官方提醒，markRaw 和浅层 API 都是高级逃生舱。markRaw 只保证被标记的根对象不被代理；若把未标记的嵌套对象另行放入 reactive 对象，仍可能出现原始对象与代理对象身份不同的情况。因此不要随意把实例的嵌套成员拆出来塞回深层响应式树。

出现问题时按这张清单回看

• 方法调用异常：确认库是否依赖对象身份，实例是否被普通 ref 或 reactive 深度代理；可先改为 shallowRef 收紧边界。
• 界面不更新：确认模板依赖的是根引用还是实例内部字段；优先把所需字段同步到独立 ref。
• 重复初始化：检查创建逻辑是否只在容器就绪后运行，以及开发环境或条件渲染是否让组件重复挂载。
• 卸载后仍有回调：确认销毁 API、事件解绑、观察器释放是否都在 onBeforeUnmount 处理。
• 团队成员频繁调用 triggerRef：复盘是否把太多业务状态藏进了浅层对象，必要时拆成可读的响应式字段。

几个常见问题

shallowRef 会把实例完全变成非响应式吗？

不会。.value 的读取和赋值仍是响应式的，只是内部对象不会被深度转换。替换根引用可以触发依赖。

用了 shallowRef 还需要 markRaw 吗？

组件内单独用 shallowRef 持有实例时通常不需要。若对象还会被放进其他深度 reactive 容器，才考虑 markRaw，并同时评估身份边界。

可以直接在模板里调用实例方法吗？

技术上可以暴露实例，但工程上更建议暴露语义化方法，例如 updateData、resize。这样更容易统一空值处理、销毁状态和后续替换第三方库。

shallowRef 能代替所有性能优化吗？

不能。它只减少不必要的深度响应式转换。渲染成本、事件频率、第三方库自身计算和 DOM 数量仍需分别分析。