深入理解 @formily/reactive 的 untracked:在响应式追踪中精确隔离依赖收集

原创2026-09-23 15:45:141,663 阅读
文章标签:前端UI组件

深入理解 @formily/reactive 的 untracked:在响应式追踪中精确隔离依赖收集

untracked 是 @formily/reactive 响应式核心暴露的一组 API(与 batch、autorun、reaction 并列),其作用是在一段给定函数执行期间临时关闭依赖收集:函数内部无论读取多少响应式数据,都不会被当前正在运行的响应式上下文(如 autorun、reaction 或组件渲染)注册为依赖。本文以 untracked.zh-CN.md 为骨架,结合源码实现与测试用例,讲清它的签名、用法、底层拦截原理,以及与 batch 的本质区别,帮助你写出更精确、可预测的响应式逻辑。

untracked 是什么:API 定位与签名

在 Formily 的响应式体系(packages/reactive)中,observable 负责把数据变成可追踪对象,autorun/reaction 负责建立"读取即依赖"的自动订阅关系。但实际业务里经常出现这类诉求:我确实要读取某个响应式值,但我不想因为它而变化而触发当前 effect 重跑——例如在 effect 里读一次配置快照、写日志、或把值传给某个不关心变化的第三方库。

untracked 就是为这种场景准备的。官方文档给出的签名如下:

interface untracked<T extends () => any> {
  (untracker?: T): ReturnType<T>
}

要点解读:

  • 入参 untracker 是一个可选函数,函数内部读取的响应式数据不会被收集为依赖;
  • 返回值类型与入参函数返回值一致(ReturnType<T>),因此它天然适合包裹有返回值的表达式,而不只是过程语句;
  • 参数可省略(untracked()),此时仅起到"切换开关"作用,不做任何计算。

从源码看,untracked 的实现极简,它由 createBoundaryFunction 配合两个反应期钩子构成,见 untracked.ts:

import { createBoundaryFunction } from './internals'
import { untrackStart, untrackEnd } from './reaction'

export const untracked = createBoundaryFunction(untrackStart, untrackEnd)

整个 API 的语义可以概括为一句话:在给定的 untracker 函数内部,永远不会被依赖收集(与 batch 的用法相似,但作用不同,下文详述)。

快速上手:从文档用例出发

文档给出了最典型的使用场景:在 autorun 中读取响应式值,但希望这个读取不影响订阅关系。

import { observable, autorun, untracked } from '@formily/reactive'

const obs = observable({
  aa: 11,
})

autorun(() => {
  console.log(untracked(() => obs.aa)) //变化时不会触发
})

obs.aa = 22

执行结果分析:

  1. autorun 首次执行时,外层函数体读取了 untracked(() => obs.aa) 的返回值;
  2. 由于读取发生在 untracked 内部,obs.aa 的依赖绑定被跳过,因此 autorun 并没有订阅 aa;
  3. 当 obs.aa = 22 修改数据并触发响应式通知时,该 autorun 不在 aa 的依赖集合中,因此 不会重跑,控制台只会打印一次 11。

对应的单元测试见 untracked.spec.ts,其中用 jest.fn 精确验证了"调用次数恒为 1"这一行为:

test('basic untracked', () => {
  const obs = observable<any>({})
  const fn = jest.fn()
  autorun(() => {
    untracked(() => {
      fn(obs.value)
    })
  })

  expect(fn).toBeCalledTimes(1)
  obs.value = 123
  expect(fn).toBeCalledTimes(1)
})

原理剖析:UntrackCount 与依赖收集的拦截

要理解 untracked 为什么能"屏蔽"依赖收集,需要追踪三个关键环节:状态计数、边界函数、绑定拦截。

第一步:状态计数开关

untrackStart / untrackEnd 的实现位于 reaction.ts:

export const untrackStart = () => {
  UntrackCount.value++
}

export const untrackEnd = () => {
  UntrackCount.value--
}

它们操作的 UntrackCount 是 environment.ts 中定义的一个模块级计数器:

export const UntrackCount = { value: 0 }

配套的判定函数:

export const isUntracking = () => UntrackCount.value > 0

也就是说,untracked 内部会把 UntrackCount 从 0 变成 1(支持嵌套叠加),从而让整个系统进入"屏蔽收集"模式。

第二步:边界函数保证成对执行

createBoundaryFunction 位于 internals.ts,它的职责是保证 start/end 在任意情况下都成对调用(即使回调抛异常,finally 也会执行 end):

export const createBoundaryFunction = (
  start: (...args: any) => void,
  end: (...args: any) => void
) => {
  function boundary<F extends (...args: any) => any>(fn?: F): ReturnType<F> {
    let results: ReturnType<F>
    try {
      start()
      if (isFn(fn)) {
        results = fn()
      }
    } finally {
      end()
    }
    return results
  }

  boundary.bound = createBindFunction(boundary)
  return boundary
}

注意两个细节:

  • 只有当传入 fn 是函数时才执行它,所以 untracked() 无参调用是合法的(测试 'no params untracked' 专门覆盖了这一点);
  • 返回的 boundary 函数还挂载了 bound 方法(由 createBindFunction 生成),用于在指定 context 下执行回调,方便把类方法直接包进 untracked 边界内。

第三步:在绑定入口处拦截

依赖收集的真正入口是 bindTargetKeyWithCurrentReaction(reaction.ts)。每当代理对象上的属性被读取,baseHandlers/collectionHandlers 都会调用它,把"当前栈顶的 reaction"与"目标对象的某个 key"关联起来:

export const bindTargetKeyWithCurrentReaction = (operation: IOperation) => {
  let { key, type, target } = operation
  if (type === 'iterate') {
    key = ITERATION_KEY
  }
  const reactionLen = ReactionStack.length
  if (reactionLen === 0) return
  const current = ReactionStack[reactionLen - 1]
  if (isUntracking()) return      // ← untracked 的拦截点
  if (current) {
    DependencyCollected.value = true
    addReactionsMapToReaction(current, addRawReactionsMap(target, key, current))
  }
}

关键就在 if (isUntracking()) return 这一行:即便此时 ReactionStack 栈顶确实存在正在执行的 autorun/reaction(说明读取确实发生在响应式上下文里),只要 UntrackCount > 0,就直接放弃注册。于是 RawReactionsMap 中不会新增"target.key → reaction"的映射,后续数据变更触发 runReactions 时自然也找不到该 reaction,effect 便不会被唤醒。

这也解释了文档中"用法与 batch 相似"的说法:两者都只是包一层边界函数(batch 走 batchStart/batchEnd),形态相似,但干预的环节完全不同(见下节)。

untracked 与 batch 的异同

batch 的边界实现同样基于 createBoundaryFunction,只是传入的是 batchStart/batchEnd(reaction.ts)。二者的对比如下:

维度 batch untracked
核心计数器 BatchCount UntrackCount
干预环节 通知执行阶段:批量收集 PendingReactions,在 batchEnd 时统一执行 依赖收集阶段:isUntracking() 为真时直接跳过绑定
影响面 延迟/合并 effect 触发,减少重复执行 完全阻断依赖注册,effect 不再订阅这些数据
典型场景 一次性修改多个字段,避免中间态触发多次 effect 读取但不订阅,读取结果变化不应影响当前 effect
组合使用 可嵌套 可嵌套(计数器叠加)

简单记忆:batch 管"什么时候触发",untracked 管"要不要订阅"。

值得留意的是,二者在实现上是正交的:runReactions 在执行通知时会把 UntrackCount 临时归零再恢复(reaction.ts),确保批量派发 effect 时不会误伤其内部正常的依赖收集;batchEnd 清空待执行队列时也有类似处理。这说明框架刻意保持了两种边界的隔离与可组合性。

边界场景与使用要点

在 computed 上使用 untracked

observable.computed 的 getter 同样受依赖收集约束。当你想"计算出一个值,但不希望它内部读取的依赖影响外层订阅"时,可以像测试 annotations.spec.ts 那样包裹:

test('computed no track get', () => {
  const obs = observable({ aa: 123 })
  const compu = observable.computed({ get: () => obs.aa })
  untracked(() => {
    expect(compu.value).toBe(123)
  })
})

在这个用例中,untracked 内部读取 compu.value 只是取回计算结果,而不会因为这次读取而让外层上下文订阅 compu 及其依赖的 obs.aa。

嵌套与无参调用

由于 UntrackCount 是累加计数器,untracked 支持嵌套;由于 createBoundaryFunction 仅在传入函数时才执行,untracked() 可作为纯开关使用(测试 'no params untracked' 保证其可空调用且不抛错)。

与 autorun / reaction 的配合

autorun 的执行体位于 ReactionStack 中(autorun.ts),reaction 的 tracker 同样入栈。因此:

  • 在 autorun 内部用 untracked 包裹的读取 → 不订阅;
  • 在 reaction 的 tracker 内部同理;
  • 在 untracked 内部调用 autorun/reaction,其内部的依赖收集不受影响(各自拥有独立边界),这与 batch 的行为一致。

使用注意

  • 它屏蔽的是"本次读取与当前 reaction 的绑定",并不影响数据本身的可观察性——其他 effect 照常订阅;
  • 不要在 untracked 回调内做"既想读取又想订阅"的操作,语义上二者互斥;
  • 若回调内部抛错,finally 会保证 untrackEnd 执行,计数器不会泄漏,但错误会照常向外传播。

结语

untracked 是 @formily/reactive 中体积最小、语义却最清晰的 API 之一:一行源码定义(untracked.ts),配合反应期计数与绑定入口的拦截(reaction.ts、reaction.ts),即可精确控制依赖收集的开关。理解它之后,你再面对"读配置不订阅""取快照不重跑"这类需求时,就有了标准答案;配合 batch 使用,则能同时控制"订阅关系"与"触发时机"两个维度,写出更符合预期、更容易推理的响应式代码。

登录后查看全文
formily