@formily/reactive-vue observer:将 Vue 组件渲染变为 Reaction 响应式追踪的完整指南

原创2026-09-23 13:06:471,990 阅读
文章标签:前端UI组件

@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>

运行逻辑拆解:

  1. observable({ value: 'Hello world' }) 创建一个 @formily/reactive 响应式对象;
  2. 模板中 :value="obs.value" 与 {{obs.value}} 在渲染阶段被 observer 追踪,obs.value 成为组件依赖;
  3. 输入框 @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:重写 mount/mount/destroy,接管原生渲染

Vue 2 分支位于 packages/reactive-vue/src/observer/observerInVue2.ts,其核心思路是:

  1. 复制原始组件选项(避免修改原组件),包装 data 为 collectData 处理后的版本;
  2. 通过 Super.extend(options) 生成扩展组件,其中 Super 取原组件的原型链构造器,规避 Vue.extend 时生命周期被重复调用的问题;
  3. 重写原型上的 $mount:首次挂载时在 batch 包裹下用 Tracker.track 执行原生渲染,并把 Vue 的 _watcher.getter 替换为 reactiveRender,使组件后续每次渲染都重新进入 Tracker 收集依赖;
  4. 重写 $destroy:组件销毁前先 dispose Tracker,杜绝销毁后的无效追踪。
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 时 dispose Tracker,防止内存泄漏;
  • 依赖变化时优先走 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 的设计是在每次渲染时重新收集依赖。这带来两个好处:

  1. 条件渲染下的依赖是动态的:if (obs.a) return obs.b 这种写法下,只有当 obs.a 为真时 obs.b 才成为依赖,之后 obs.b 的变化不会在 obs.a 为假时误触发渲染;
  2. 依赖集合始终精确收敛到"当前视图真正消费的数据"。

代价是每次渲染都需要一次追踪开销,但 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 帮助调试与组件树识别。

深入阅读建议:

登录后查看全文
formily