@formily/reactive-vue observer:将 Vue 组件渲染变为 Reaction 响应式追踪的完整指南
@formily/reactive-vue observer:将 Vue 组件渲染变为 Reaction 响应式追踪的完整指南
导读
在 Formily 体系中,@formily/reactive 提供了独立于框架的响应式内核,而 @formily/reactive-vue 则负责把这一内核接入 Vue 的组件生命周期。本文聚焦 @formily/reactive-vue 的核心 API —— observer:它能把一个 Vue 组件的渲染方法改造成一个 Reaction,使得组件每次重新渲染时自动收集所消费的响应式依赖,并在依赖变化时精准触发重渲染。读完本文,你将掌握 observer 的签名与参数语义、Vue 2 / Vue 3 双版本下的底层实现原理、scheduler 调度器的正确用法,以及它与 Vue 原生响应系统的共存方式。
本文基于当前仓库中 packages/reactive/docs/api/vue/observer.md 编写,并以 packages/reactive-vue 包的真实源码与测试用例作为佐证。
一、核心概念:把渲染函数变成 Reaction
observer 的官方描述非常凝练:
In Vue, the component rendering method is changed to Reaction, and dependencies are collected every time the view is re-rendered, and dependencies are updated automatically to re-render.
翻译过来即:在 Vue 中,将组件渲染方法变成 Reaction,每次视图重新渲染时收集依赖,依赖更新时自动重渲染。
要理解这句话,需要先了解 @formily/reactive 中两个核心原语(详见 packages/reactive/src/index.ts 及文档 packages/reactive/docs/api/reaction.md):
- observable:把普通对象包装成可被追踪的响应式数据;
- Tracker / reaction:执行一段函数(effect),在函数执行期间读取到的 observable 属性会被自动登记为依赖,此后任何依赖变化都会触发 effect 重新执行。
observer 的工作,就是把 Vue 组件的 render 逻辑放进这样一个 Tracker 中执行:渲染期间读到的 observable 属性全部成为该组件的依赖;此后只要任一依赖变化,组件就会自动进入重渲染流程。这正是 Formily 表单元件能以高性能、细粒度方式响应表单状态变化的基础设施。
二、API 签名与参数说明
2.1 完整签名
原文档给出了如下 TypeScript 签名:
interface IObserverOptions {
scheduler?: (updater: () => void) => void //调度器,可以手动控制更新时机
name?: string //包装后的组件的name
}
interface observer<T extends VueComponent> {
(component: T, options?: IObserverOptions): T
}
observer 接收一个 Vue 组件(选项对象或类组件)和可选配置,返回一个包装后的等价组件;返回值的类型保持 T 不变,因此对调用方而言 API 形状完全透明。
该签名与仓库中 packages/reactive-vue/src/types.ts 的定义一一对应:
export interface IObserverOptions {
name?: string
scheduler?: (updater: () => void) => void
}
2.2 参数语义
| 参数 | 类型 | 说明 | 默认行为 |
|---|---|---|---|
component |
T extends VueComponent |
待包装的 Vue 组件(选项对象或 Vue 类) | 必填 |
options.name |
string |
包装后组件的名称 | 优先取显式传入的 name,其次回退到组件自身 name / _componentTag / 构造函数名,最终回退到 '<component>' |
options.scheduler |
(updater: () => void) => void |
调度器,在依赖变化时接管重渲染的时机控制 | 不传则依赖变化后立即同步重渲染 |
关于 name 的回退优先级,源码 packages/reactive-vue/src/observer/observerInVue2.ts 给出了精确顺序:
const name =
observerOptions?.name ||
(Component as any).name ||
(Component as any)._componentTag ||
(Component.constructor && Component.constructor.name) ||
'<component>'
对应的测试 packages/reactive-vue/src/tests/observer.spec.ts 验证了两种边界:无任何名称时最终得到 '<component>',显式传入 { name: 'abc' } 时得到 'abc'。
2.3 scheduler 的用途
scheduler 是 IObserverOptions 中最有实战价值的参数:当依赖更新发生时,observer 不会直接执行重渲染,而是把"执行重渲染"这个动作(即 updater 回调)交给你手动编排。典型场景包括:
- 合并高频更新:在一帧内多次修改响应式数据时,只调度一次渲染;
- 延迟渲染:配合
setTimeout/requestAnimationFrame把渲染推迟到合适时机; - 异步批量刷新:把更新任务推入自己的批处理队列。
测试 packages/reactive-vue/src/tests/observer.spec.ts 给出了一个完整的节流式 scheduler 示例:100ms 内的多次更新被合并为一次渲染。
三、完整用例:与 Vue 响应系统共存
原文档提供了一段开箱即用的示例。一个值得强调的设计点是:observer 包装后的组件 不排斥 Vue 原生响应系统——data() 中既可以是普通 Vue 响应式数据,也可以混入 @formily/reactive 的 observable 对象,两者可以在同一组件中并存。
<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,
}
},
})
</script>
运行逻辑拆解:
observable({ value: 'Hello world' })创建一个@formily/reactive响应式对象;- 模板中
:value="obs.value"与{{obs.value}}在渲染阶段被observer追踪,obs.value成为组件依赖; - 输入框
@input事件改写obs.value,依赖变化触发 Tracker 回调,组件自动重渲染,视图同步更新。
3.1 共存机制:collectData 的过滤逻辑
"能与 Vue 响应系统共存"不是一句口号,其底层实现位于 packages/reactive-vue/src/observer/collectData.ts。observer 在 Vue 2 分支中会重写 data 选项,用 collectData 对 data() 的返回值做分流处理:
export default function collectData(vm: any, data?: any) {
const dataDefinition =
typeof data === 'function' ? data.call(vm, vm) : data || {}
const filteredData = Object.keys(dataDefinition).reduce(
(result: any, field) => {
const value = dataDefinition[field]
if (isObservable(value)) {
Object.defineProperty(vm, field, {
configurable: true,
get() {
return value
},
})
} else {
result[field] = value
}
return result
},
{}
)
return filteredData
}
关键行为:
- 对
data()返回的每个字段调用isObservable(来自@formily/reactive)做判定; - 若是
observable对象,则不交给 Vue 的响应式系统,而是直接在vm上定义 getter 透传引用,避免 Vue 对已代理对象再次递归代理带来的性能损耗与行为冲突; - 若是普通数据,则保持原样交给 Vue 处理,与 Vue 原生响应系统无缝衔接。
对应的测试 packages/reactive-vue/src/tests/observer.spec.ts 验证了这一点:经过 collectData 过滤后,model(observable)仍由 @formily/reactive 追踪并触发 autorun,而普通字段 target 完全不受 @formily/reactive 影响。
四、双版本实现:Vue 2 与 Vue 3 的分流
@formily/reactive-vue 借助 vue-demi 同时支持 Vue 2 与 Vue 3。入口 packages/reactive-vue/src/observer/index.ts 根据 isVue2 标志分发到两套实现:
export function observer<C>(baseComponent: C, options?: IObserverOptions): C {
if (isVue2) {
return observerV2(baseComponent, options)
} else {
return observerV3(baseComponent, options)
}
}
依赖关系(见 packages/reactive-vue/package.json):运行时依赖 @formily/reactive@2.3.7 与 vue-demi@>=0.13.6,同时以 vue@^2.6.0 || >=3.0.0-rc.0 和 @vue/composition-api(Vue 2 下使用 Composition API 时需要)作为 peer 依赖。
4.1 Vue 2:重写 destroy,接管原生渲染
Vue 2 分支位于 packages/reactive-vue/src/observer/observerInVue2.ts,其核心思路是:
- 复制原始组件选项(避免修改原组件),包装
data为collectData处理后的版本; - 通过
Super.extend(options)生成扩展组件,其中Super取原组件的原型链构造器,规避Vue.extend时生命周期被重复调用的问题; - 重写原型上的
$mount:首次挂载时在batch包裹下用Tracker.track执行原生渲染,并把 Vue 的_watcher.getter替换为reactiveRender,使组件后续每次渲染都重新进入 Tracker 收集依赖; - 重写
$destroy:组件销毁前先disposeTracker,杜绝销毁后的无效追踪。
const reactiveRender = () => {
batch(() => {
tracker.track(() => {
if (!mounted) {
$mount.apply(this, args)
mounted = true
nativeRenderOfVue = this._watcher.getter
// rewrite the native render method of vue with our reactive tracker render
// thus if component updated by vue watcher, we could re track and collect dependencies by @formily/reactive
this._watcher.getter = reactiveRender
} else {
nativeRenderOfVue.call(this, this)
}
})
})
return this
}
而 Tracker 的回调则负责在依赖变化时决定"何时、以何种方式"重渲染:
const tracker = new Tracker(() => {
if (
reactiveRender.$vm._isBeingDestroyed ||
reactiveRender.$vm._isDestroyed
) {
return tracker.dispose()
}
if (
observerOptions?.scheduler &&
typeof observerOptions.scheduler === 'function'
) {
observerOptions.scheduler(reactiveRender)
} else {
reactiveRender()
}
})
这里有两处值得注意的实现细节:
- 销毁保护:检测到组件处于
_isBeingDestroyed/_isDestroyed状态时直接tracker.dispose()。测试 packages/reactive-vue/src/tests/observer.spec.ts 专门验证了"watcher 销毁后不再触发渲染"这一行为; - scheduler 接管:依赖变化时优先调用用户传入的
scheduler,否则立即reactiveRender()。
4.2 Vue 3:setup 内注入 useObserver
Vue 3 分支位于 packages/reactive-vue/src/observer/observerInVue3.ts,实现更加轻量:包装返回一个带 setup 的新组件,在用户 setup 执行前先调用 useObserver 建立追踪:
export const observer = function (opts: any, options?: IObserverOptions): any {
const name = options?.name || opts.name || 'ObservableComponent'
return {
name,
...opts,
setup(props: Record<string, any>, context: any) {
useObserver(options)
return opts?.setup?.(props, context)
},
}
}
useObserver 定义在 packages/reactive-vue/src/hooks/useObserver.ts:在组件实例上拦截 effect 属性,把组件更新函数包装进 Tracker.track,并支持:
onBeforeUnmount时disposeTracker,防止内存泄漏;- 依赖变化时优先走
options.scheduler,否则调用vm.proxy.$forceUpdate()强制重渲染。
需要说明的是,这段实现中有一个对 Formily 官方 issue(#2655)的兼容性处理,其细节随 Vue 版本迭代可能有差异,本文仅陈述源码当前状态。
五、在 Formily 生态中的定位与典型用法
5.1 使用入口
@formily/reactive-vue 的公共导出(见 packages/reactive-vue/src/index.ts)包含三部分:
export * from './observer'
export * from './hooks'
export * from './types'
即 observer(含 collectData)、useObserver hook 以及 IObserverOptions 类型。安装后在项目中即可直接使用:
# 以 npm 为例
npm install @formily/reactive-vue
使用时注意 Vue 2 场景需自行安装 vue@^2.6.0 并视情况引入 @vue/composition-api(Vue 3 则直接使用 vue@>=3)。
5.2 何时使用 observer
从源码与测试可以归纳出 observer 的典型适用场景:
- 组件内消费了
@formily/reactive的 observable 数据(例如 Formily 表单模型Form/Field的value、errors、loading等状态); - 希望渲染粒度精确到组件级:只有真正读取到的依赖变化才触发本组件重渲染,而不是整棵组件树重渲染;
- 需要手动控制更新时机(配合
scheduler)做渲染合并或延迟渲染。
5.3 与 React 版本 observer 的差异
当前仓库同时提供了 React 版本文档 packages/reactive/docs/api/react/observer.md,两者理念相同(把渲染变成 Reaction),但存在明显差异:
| 维度 | @formily/reactive-vue |
@formily/reactive-react |
|---|---|---|
| 支持组件形态 | Vue 组件(选项对象 / 类 / 带 setup 的组件) | 仅函数组件(Function Component) |
| 名称配置项 | name |
displayName |
| 透传 ref 配置 | 无 | forwardRef |
| 附加能力 | collectData 与 Vue 响应系统共存 |
Observer 组件(Render Props 局部精确渲染) |
这一对照可以帮助你在跨框架复用 Formily 响应式状态时快速对齐 API 语义。
六、常见问题与最佳实践
6.1 依赖收集"每次渲染都发生"是特性而非缺陷
observer 的设计是在每次渲染时重新收集依赖。这带来两个好处:
- 条件渲染下的依赖是动态的:
if (obs.a) return obs.b这种写法下,只有当obs.a为真时obs.b才成为依赖,之后obs.b的变化不会在obs.a为假时误触发渲染; - 依赖集合始终精确收敛到"当前视图真正消费的数据"。
代价是每次渲染都需要一次追踪开销,但 batch 与细粒度收集保证了整体成本可控。
6.2 scheduler 的正确姿势
scheduler 的 updater 就是"执行重渲染"的函数,务必在合适时机调用且不要重复调用。参考测试中的节流写法:
const Component = observer(
{
data() {
return { model }
},
render(h) {
return h('button', {
on: { click: this.model.setAge },
domProps: { textContent: this.model.age },
})
},
},
{
scheduler: (update) => {
clearTimeout(timer)
timer = setTimeout(update, 100)
},
}
)
要点:
- 连续触发时先
clearTimeout再重新计时,实现"最后一次生效"的合并效果; - 组件销毁后 Tracker 已 dispose,不应再调度渲染。
6.3 组件销毁后的安全性
observer 两套实现都内置了销毁保护:
- Vue 2:Tracker 回调检测
_isBeingDestroyed/_isDestroyed后自动dispose,$destroy也会显式执行 disposer(见 observerInVue2.ts); - Vue 3:
useObserver在onBeforeUnmount中 dispose Tracker(见 useObserver.ts)。
因此无需在业务代码里手动清理,这也是测试 observer.spec.ts 覆盖的核心保障之一。
6.4 不要混用两套响应式代理同一对象
尽管 collectData 已自动把 observable 对象从 Vue 响应式系统中"摘出",但建议在业务层保持清晰边界:同一份状态要么归 @formily/reactive 管,要么归 Vue 管,避免对同一对象同时施加两套代理导致的行为不确定性。
七、小结
observer 是 @formily/reactive-vue 的基石 API,它把 Vue 组件的渲染生命周期与 @formily/reactive 的响应式追踪机制打通:
- 每次渲染收集依赖、依赖更新自动重渲染,实现组件级精确更新;
- 通过
collectData与 Vue 原生响应系统和平共存; - Vue 2 分支重写
$mount/$destroy并接管原生渲染,Vue 3 分支通过setup+useObserver注入追踪; scheduler提供手动编排渲染时机的自由,name帮助调试与组件树识别。
深入阅读建议: