Formily reactive-vue observer 完全指南:把 Vue 组件渲染变成可自动追踪的 Reaction
Formily reactive-vue observer 完全指南:把 Vue 组件渲染变成可自动追踪的 Reaction
导读
在 Formily 的响应式体系中,@formily/reactive 负责提供跨框架的响应式核心(observable、Tracker、batch 等),而 @formily/reactive-vue 则是它面向 Vue 生态的桥接层。本文围绕 packages/reactive/docs/api/vue/observer.zh-CN.md 展开,深入讲解 observer 这一核心 API:如何将 Vue 组件的渲染方法改造成一个 Reaction,让每次视图渲染自动收集 @formily/reactive 依赖,依赖更新时自动触发重渲染。读完本文,你将掌握 observer 的完整签名、scheduler 与 name 两个配置项的实战含义,并通过 Vue 2 / Vue 3 双版本源码与单元测试,理解其“依赖收集—批量调度—精准更新—自动释放”的完整闭环。
一、observer 是什么:把“渲染”升级为“Reaction”
observer 是 @formily/reactive-vue 提供的组件包装函数。按照文档描述,它的核心职责是:
在 Vue 中,将组件渲染方法变成 Reaction,每次视图重新渲染就会收集依赖,依赖更新会自动重渲染。
也就是说,observer 让 Vue 组件内部访问到的 @formily/reactive 可观察对象(由 observable 创建)与组件视图之间建立起自动绑定:
- 渲染即收集:组件每次执行渲染函数时,凡是访问到的
observable属性都会被自动登记为该组件的依赖; - 更新即重渲染:当这些依赖属性发生变化时,组件会自动重新渲染,无需手动调用
$forceUpdate或依赖 Vue 自身的data响应系统。
从实现上看,observer 与 Vue 自身的响应式系统并不冲突,它可以共存:既可以在 data() 中返回 observable 对象,也可以继续使用 Vue 原有的响应式数据(下文源码分析会解释 collectData 如何做到这一点)。
二、API 签名与参数详解
observer 的类型签名如下(与文档一致,且与 packages/reactive-vue/src/types.ts 中的 IObserverOptions 完全对应):
interface IObserverOptions {
scheduler?: (updater: () => void) => void // 调度器,可以手动控制更新时机
name?: string // 包装后的组件的 name
}
interface observer<T extends VueComponent> {
(component: T, options?: IObserverOptions): T
}
两个可选参数各有明确用途:
| 参数 | 类型 | 作用 | 默认行为 |
|---|---|---|---|
scheduler |
(updater: () => void) => void |
依赖变化后,接管“何时执行更新”的调度权。updater 是真正触发重渲染的回调 |
不传时依赖变化立即同步触发重渲染 |
name |
string |
显式指定包装后组件的名称 | 依次回退到组件自身 name、_componentTag、构造函数名,最终兜底为 <component>(Vue 2)或 ObservableComponent(Vue 3) |
关于 name 的取值优先级,源码中给出了明确的证据链:
- Vue 2 版本 observerInVue2.ts 中的解析顺序为:
options.name→ 组件对象name→_componentTag→ 构造函数名 →'<component>'; - Vue 3 版本 observerInVue3.ts 则为:
options.name→ 组件对象name→'ObservableComponent'。
对应测试 observer.spec.ts 验证了这一点:匿名组件对象包装后名称回退为 <component>,传入 { name: 'abc' } 后名称变为 abc。
三、最小可用用例:observable + observer
文档给出的用例展示了最核心的组合:用 @formility/reactive 的 observable 创建外部响应式数据,再用 @formility/reactive-vue 的 observer 包装组件。
<template>
<div>
<div>
<input
:style="{
height: 28,
padding: '0 8px',
border: '2px solid #888',
borderRadius: 3,
}"
:value="obs.value"
@input="(e) => {
obs.value = e.target.value
}"
/>
</div>
<div>{{obs.value}}</div>
</div>
</template>
<script>
import { observable } from '@formily/reactive'
import { observer } from '@formily/reactive-vue'
export default observer({
data() {
// 能与 vue 的响应系统共存
const obs = observable({
value: 'Hello world',
})
return {
obs,
}
},
name: 'HelloWorld', // 可选:自定义组件名
})
</script>
拆解这段代码的行为链:
observable({ value: 'Hello world' })在data()中创建一个@formily/reactive可观察对象,并放进 Vue 的data返回结果中——它同时出现在 Vue 与 Formily 两套响应系统面前,但observer会保证它的响应式更新走 Formily 通道;- 模板中
:value="obs.value"与{{obs.value}}在渲染时读取了obs.value,这两次读取被Tracker记录为依赖; - 用户在输入框输入时,
@input回调直接修改obs.value(绕过 Vue 的 setter),observer检测到该依赖变化后自动触发组件重渲染,页面上的文本随之更新。
整个过程无需任何手动订阅或事件广播,这正是“渲染即收集、更新即重渲染”的直观体现。
四、源码级原理:Vue 2 与 Vue 3 的双版本实现
observer 并不是单一实现,而是根据运行环境自动分发。入口 observer/index.ts 利用 vue-demi 的 isVue2 判断:
export function observer<C>(baseComponent: C, options?: IObserverOptions): C {
/* istanbul ignore else */
if (isVue2) {
return observerV2(baseComponent, options)
} else {
return observerV3(baseComponent, options)
}
}
这意味着同一个包可以同时服务于 Vue 2 与 Vue 3 项目(依赖 vue-demi 桥接),下面分别剖析两条实现路径。
4.1 Vue 2 实现:重写 $mount / $destroy,注入 Tracker
Vue 2 的实现位于 observerInVue2.ts,核心策略是构造一个扩展组件,并重写其生命周期:
- 不污染原组件:通过
Super.extend(options)基于原组件选项构造新的扩展组件(Super是原组件构造函数原型链上的 Vue 构造器,避免 Vue Class 组件被二次 extend 导致生命周期执行两次); - data 改造:用
collectDataForVue包裹原data定义(详见下文); - 重写
$mount(L49-L97):首次挂载时在batch(() => tracker.track(...))内调用原生$mount,随后取出 Vue 的_watcher.getter(即 Vue 原生渲染函数),把它替换为reactiveRender。此后每次 Vue watcher 触发渲染,都会重新进入tracker.track,从而重新收集@formily/reactive依赖; - 依赖变化驱动:
new Tracker(() => {...})(L76-L92)订阅依赖变化,回调中先判断组件是否处于销毁状态(_isBeingDestroyed/_isDestroyed),若已销毁则tracker.dispose()释放资源;否则优先调用observerOptions.scheduler(reactiveRender),缺省时直接reactiveRender(); - 重写
$destroy(L99-L102):销毁前先执行disposerSymbol(即tracker.dispose),确保组件销毁后不再被依赖更新误触。
这里用到的 Tracker 来自 @formily/reactive 核心,其实现见 tracker.ts:track() 方法将当前 Reaction 压入 ReactionStack,在 batchStart/batchEnd 包裹下执行 tracker 回调以收集依赖;dispose() 通过 disposeBindingReactions 解绑所有已登记依赖。observer 正是把“重渲染”包装成了一个这样的 Reaction。
4.2 Vue 3 实现:setup + useObserver + $forceUpdate
Vue 3 的实现更轻量,位于 observerInVue3.ts:它返回一个新组件对象,在 setup 中调用 useObserver.ts 完成接入:
- 通过
vue-demi的getCurrentInstance()拿到当前组件实例; - 定义
vmUpdate = () => vm?.proxy?.$forceUpdate()作为默认更新回调; onBeforeUnmount(disposeTracker)在组件卸载前销毁Tracker,避免内存泄漏;- 借助 Vue 3 内部的
effect属性(vm['_updateEffect']),把组件的渲染 effect 的run方法替换为tracker.track(() => refn = vm['_updateEffectRun'].call(newValue)),从而在每次 Vue 渲染时经由Tracker收集 Formily 依赖; - 依赖变化时同样遵循:存在
options.scheduler则交给调度器,否则直接vmUpdate()触发$forceUpdate。
可见 Vue 2 与 Vue 3 的实现路径虽然不同,但都收敛到同一个机制:用 Tracker 包裹渲染、依赖变化后执行 scheduler 或直接更新。
4.3 collectData:让两套响应式数据共存
Vue 2 路径中的 collectData.ts 解决了“Vue 响应式数据与 Formily 可观察对象并存”的问题:它对 data() 返回的每个字段逐一检查——若值是 isObservable 的可观察对象,则用 Object.defineProperty 将其作为只读属性挂到组件实例 vm 上(避免 Vue 再对其实施一层代理,从而保留 Formily 的响应式语义);其余普通字段则原样返回,继续走 Vue 自身的响应式通道。
对应测试 observer.spec.ts 验证了该行为:model(observable)放进 data 后,autorun 能感知其变更(fn1 被调用两次);而普通字段 target 交给 Vue 处理,不会干扰 Formily 的追踪(fn2 只调用一次)。
五、scheduler 调度器:手动掌控更新时机
IObserverOptions.scheduler 是 observer 最实用的进阶能力。默认情况下,任何依赖变化都会同步触发组件重渲染;而在高频更新场景(如输入框连打、列表批量变更)中,这会造成不必要的渲染开销。通过 scheduler,可以把多次更新合并成一次:
import { observer } from '@formily/reactive-vue'
import { observable } from '@formily/reactive'
const model = observable({
age: 10,
setAge() {
model.age++
},
})
const Component = observer(
{
data() {
return { model }
},
render(h) {
return h('button', {
on: { click: this.model.setAge },
domProps: { textContent: this.model.age },
})
},
},
{
// 把渲染调度到下一次宏任务:100ms 内的连续更新只渲染一次
scheduler: (update) => {
clearTimeout(this._t)
this._t = setTimeout(() => update(), 100)
},
}
)
这里的 update 就是 observer 内部提供的重渲染回调,调度器负责决定“何时调用它”。源码中 scheduler 的生效点在 Vue 2 的 observerInVue2.ts 与 Vue 3 的 useObserver.ts,两处逻辑一致:检测到 scheduler 为函数时调用之,否则直接更新。
测试 observer.spec.ts 给出了标准验证:两次快速点击 setAge 后,在 150ms 时断言按钮文本分别从 10 变为 11、再变为 12,证明调度器节流后的更新依然准确、不丢状态。
六、生命周期与资源释放
observer 的自动追踪并非永久有效,它随组件生命周期创建与销毁:
- 创建:组件挂载(Vue 2 的
$mount/ Vue 3 的setup)时创建Tracker并开始收集依赖; - 销毁:
- Vue 2:
$destroy被重写,先执行tracker.dispose()再走原生销毁流程; - Vue 3:
onBeforeUnmount中执行disposeTracker();
- Vue 2:
- 兜底保护:依赖更新回调中若检测到组件实例已标记销毁(
_isBeingDestroyed/_isDestroyed),会立即tracker.dispose(),不再触发渲染。
对应测试 observer.spec.ts 验证了这一点:将组件实例标记为已销毁后修改 model.age,渲染计数保持为 1(不再触发 reactiveRender),确认了销毁后依赖更新不会导致无效渲染。
七、周边配套与阅读指引
- API 文档:packages/reactive/docs/api/vue/observer.zh-CN.md(本文主体),英文版见 observer.md;
- 源码入口:packages/reactive-vue/src/observer/index.ts、observerInVue2.ts、observerInVue3.ts;
- 核心 Hook:packages/reactive-vue/src/hooks/useObserver.ts,Vue 3 组合式接入点;
- 依赖收集核心:packages/reactive/src/tracker.ts,
Tracker类实现; - 测试验证:packages/reactive-vue/src/tests/observer.spec.ts,覆盖自动重渲染、组合式 API、scheduler 节流、销毁清理、collectData 与组件命名等全部关键行为;
- 包入口:packages/reactive-vue/src/index.ts 统一导出
observer、hooks 与类型。
结语
observer 是 @formily/reactive-vue 连接 Formily 响应式内核与 Vue 视图层的枢纽:它把“组件渲染”抽象为可收集依赖、可调度的 Reaction,让 observable 数据的变更以最小代价精准驱动视图更新,同时通过 scheduler 提供手动节流能力、通过生命周期钩子保证资源及时释放。理解它的双版本实现与 Tracker 机制,是在 Vue 2 / Vue 3 项目中正确使用 Formily 响应式能力、排查“不更新/多渲染”类问题的关键一步。