@formily/reactive untracked 完全指南:为响应式追踪构建"不被收集"的读取边界

原创2026-09-23 20:46:021,379 阅读
文章标签:前端UI组件

@formily/reactive untracked 完全指南:为响应式追踪构建"不被收集"的读取边界

untracked 是 @formily/reactive 提供的一个边界函数(Boundary Function),它允许开发者在响应式追踪(如 autorun 的依赖收集)进行期间,将某一段同步代码内的所有可观察属性读取排除在依赖收集之外。本文以 untracked.md 为骨架,结合 packages/reactive 的源码实现与测试用例,完整讲解其签名、用法、底层原理及与 batch、action、computed 的协作关系。读完你将能够在 Formily 表单模型或任意基于 @formily/reactive 的应用中,精准控制"哪次读取不该触发重执行",写出性能更可控的响应式逻辑。

认识 untracked:一个"只读不追踪"的边界

官方文档对 untracked 的描述非常简洁:

Usage is similar to batch, and will never be collected by dependencies within a given untracker function

即:用法与 batch 相似,在给定的 untracker 函数内部,任何可观察对象的读取都永远不会被依赖收集器收集。

换句话说,当你在 autorun(或 reaction、Tracker)的追踪函数里用 untracked 包裹某段读取逻辑时,这段逻辑读取的字段不会成为当前响应式任务(Reaction)的依赖。后续这些字段无论怎么变化,都不会触发该任务的重新执行。

这与 batch 有本质区别:

  • batch 解决的是"通知时机"问题——延迟副作用执行、批量合并通知;
  • untracked 解决的是"依赖关系"问题——直接切断读取与依赖的绑定。

两者在 @formily/reactive 中是正交的两个开关(分别对应 BatchCount 与 UntrackCount 两个计数器)。

函数签名与参数说明

文档给出的类型签名如下:

interface untracked<T extends () => any> {
  (untracker?: T): ReturnType<T>
}
要素 说明
参数 untracker 可选的回调函数,类型为 () => any。传入后会在"取消追踪"上下文中同步执行;不传则为空操作(内部不做任何事)
返回值 ReturnType<T>,即 untracker 回调的返回值会被原样透传,便于在表达式中内联使用
调用方式 untracked(() => ...) 或 untracked()(无参调用同样安全)

参数是可选的这一点在测试中得到了直接验证:untracked.spec.ts 中专门有一条 no params untracked 用例,直接调用 untracked() 不抛异常。

从源码看,untracked.ts 的实现只有短短几行:

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

export const untracked = createBoundaryFunction(untrackStart, untrackEnd)

它由通用的 createBoundaryFunction 工厂构造,核心行为是"进入时 start,执行回调,无论成功失败最后 end",保证了计数必然成对增减(详见下文原理章节)。

基础示例:让 autorun 忽略某次读取

文档给出了如下示例,我们逐行拆解:

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

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

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

obs.aa = 22

执行流程分析:

  1. observable({ aa: 11 }) 创建响应式代理对象;
  2. autorun 首次执行追踪函数,此时 obs.aa 的读取发生在 untracked(() => obs.aa) 内部;
  3. 由于读取发生在"取消追踪"上下文中,依赖收集器没有把 aa 记到该 autorun 上;
  4. 因此 obs.aa = 22 修改字段后,console 不会再次输出——aa 的变化与该 autorun 无关。

仓库测试 untracked.spec.ts 用 jest.fn() 精确验证了这一行为:

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 为什么能切断依赖,需要沿着调用链深入源码。

第一步:边界工厂的 try/finally 保证

internals.ts 中 createBoundaryFunction 的实现:

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
}

关键点有两个:

  • 使用 try ... finally 包裹,即使 fn 内部抛异常,end() 也一定会执行,不会让全局的"未追踪计数"泄漏;
  • 通过 isFn(fn) 判断,非函数(包括不传参)时跳过执行,仅完成 start/end 的空转。

第二步:全局计数器的增减

start/end 对应 reaction.ts 中的 untrackStart / untrackEnd:

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

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

UntrackCount 是定义在 environment.ts 中的一个模块级共享状态:

export const ReactionStack: Reaction[] = []
export const BatchCount = { value: 0 }
export const UntrackCount = { value: 0 }

UntrackCount.value > 0 即表示当前正处于"取消追踪"作用域内,该状态由 reaction.ts 暴露为 isUntracking():

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

由于计数可叠加,untracked 支持任意层级的嵌套——每一层进入 +1、退出 -1,只有全部退出后才恢复追踪。

第三步:依赖收集器门口的闸门

真正"拦截"依赖收集的地方在 reaction.ts 的 bindTargetKeyWithCurrentReaction:

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          // ← 取消追踪时直接短路
  if (current) {
    DependencyCollected.value = true
    addReactionsMapToReaction(current, addRawReactionsMap(target, key, current))
  }
}

这段逻辑是响应式系统对"一次属性读取"的公共处理入口(由代理的 get 拦截器触发)。当 isUntracking() 为真时,函数直接 return,target + key 就不会被登记到当前 Reaction 的依赖映射 RawReactionsMap 中。于是后续该字段变化时,Reaction 的依赖比对里根本找不到这条记录,自然也就不会触发重新执行——这正是 untracked 语义的最终落点。

整个链路可以概括为:

untracked(fn)
  └─ untrackStart()        → UntrackCount.value++ (进入未追踪域)
       └─ fn()             → 读取触发 get 拦截器
            └─ bindTargetKeyWithCurrentReaction
                 └─ isUntracking() === true → 短路,不登记依赖
  └─ untrackEnd()          → UntrackCount.value-- (退出未追踪域)

untracked 与 batch、action 的关系

文档明确提到"用法与 batch 相似",二者同源但有分工。我们对比源码来厘清:

batch:只延迟、不切断

batch.ts 的实现:

export const batch: IBatch = createBoundaryAnnotation(batchStart, batchEnd)
batch.scope = createBoundaryAnnotation(batchScopeStart, batchScopeEnd)
batch.endpoint = (callback?: () => void) => {
  if (!isFn(callback)) return
  if (BatchCount.value === 0) {
    callback()
  } else {
    BatchEndpoints.add(callback)
  }
}

batchStart/batchEnd(reaction.ts)通过 BatchCount.value 的增减,把 batchEnd 时产生的 pending reactions 延后到计数归零后才统一执行。也就是说 batch 只是推迟了"通知与重执行",读取仍然会被收集为依赖,只是重执行延后、合并了。

action:batch 与 untracked 的合体

action.ts 是两者组合的最好例证:

export const action: IAction = createBoundaryAnnotation(
  () => {
    batchStart()
    untrackStart()
  },
  () => {
    untrackEnd()
    batchEnd()
  }
)

action 在进入时同时开启 batchStart 与 untrackStart,退出时对称关闭。从源码结构看,可以推断:action 的本质就是"批量 + 不追踪"的组合边界——既合并通知,又让 action 内部对可观察对象的读取不参与外部依赖收集。

三者对比

边界函数 依赖是否被收集 副作用通知 典型用途
untracked 否(isUntracking() 短路) 立即 读取一次性数据、配置、元数据
batch 是 延后合并(BatchCount 归零后统一执行) 连续修改多个字段,减少重执行次数
action 否 延后合并 事件回调/提交逻辑中批量改值,同时避免外部追踪

进阶场景:computed 在 untracked 中的行为

untracked 不仅影响普通字段读取,还影响计算属性(computed)的取值方式。在 computed.ts 的 get() 中可以看到:

function get() {
  if (hasRunningReaction()) {
    bindComputedReactions(reaction)
  }
  if (!isUntracking()) {
    // 如果允许 untracked 过程中收集依赖,那么永远不会存在绑定,因为 _dirty 已经设置为 false
    if (reaction._dirty) {
      reaction()
      reaction._dirty = false
    }
  } else {
    compute()
  }
  bindTargetKeyWithCurrentReaction({
    target: context,
    key: property,
    type: 'get',
  })
  return store.value
}

含义是:在正常追踪上下文中,读取 computed 会执行其内部依赖收集并缓存;而在 untracked 作用域内,computed 会跳过自身的 Reaction 执行(包括内部依赖的绑定与缓存更新),直接调用 compute() 现场计算一次值。这在语义上是合理的——既然外部不收集依赖,那么 computed 自身维护的 dirty 缓存、依赖绑定在这个上下文里也失去了意义,直接求值最省开销。

仓库测试 annotations.spec.ts 验证了"在 untracked 中读取 computed 不会被收集":

test('computed no track get', () => {
  const obs = observable({ aa: 123 })
  const compu = observable.computed({ get: () => obs.aa })
  untracked(() => {
    expect(compu.value).toBe(123)  // 值可正常读出
  })
})

使用注意事项与最佳实践

结合源码实现,使用 untracked 时有以下几点值得注意:

  1. 回调必须是同步函数。依赖收集的开启与关闭依赖 UntrackCount 计数,而 untrackStart/untrackEnd 在同一个同步调用栈内对称执行,异步操作中的读取无法被 untracked 覆盖。

  2. 异常安全已由实现保证。createBoundaryFunction 使用 try ... finally,回调抛错也会正确执行 untrackEnd(),不会污染后续代码的追踪状态——因此不需要手动兜底 try/catch。

  3. 无参调用安全。untracked() 等价于一次空转的 start/end,可用于"占位"或条件化包装,测试用例已覆盖。

  4. 支持嵌套。UntrackCount 是计数器而非布尔值,多层 untracked 嵌套可以正常工作,最外层退出后恢复追踪。

  5. 读取 computed 时行为不同。如前文所述,untracked 内读取 computed 会走"直接计算"分支,若你的 computed 内部有昂贵计算且希望复用缓存,应避免在 untracked 中读取它。

  6. 可作为依赖收集的性能工具。在 autorun/reaction 的追踪函数里,用 untracked 包裹"不参与响应"的读取(如临时中间量、仅用于分支判断的全局配置),可以减少无效依赖,避免字段频繁变化引发不必要的重执行。

  7. .bound 变体。从 internals.ts 的实现可以看到,untracked 上还挂载了 bound 变体(createBindFunction),用于将回调与指定 context 绑定后在边界内执行;它是边界函数工厂的通用能力,需要绑定 this 场景时可以使用。

总结

untracked 是 @formily/reactive 响应式体系中最基础的边界原语之一:它通过 UntrackCount 计数器配合 isUntracking() 短路,在 bindTargetKeyWithCurrentReaction 这一依赖收集的唯一入口处精准拦截,实现"读取但不订阅"。它与 batch(延迟通知)正交,并与 batch 组合构成了 action 的底层实现;对 computed 则退化为"直接计算"。无论是优化 autorun 的依赖集合,还是实现只读一次的配置读取,untracked 的实现源码、边界工厂与测试用例都值得作为深入 Formily 响应式内核的第一份参考资料。

登录后查看全文
formily