@formily/reactive untracked 完全指南:为响应式追踪构建"不被收集"的读取边界
@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
执行流程分析:
observable({ aa: 11 })创建响应式代理对象;autorun首次执行追踪函数,此时obs.aa的读取发生在untracked(() => obs.aa)内部;- 由于读取发生在"取消追踪"上下文中,依赖收集器没有把
aa记到该 autorun 上; - 因此
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 时有以下几点值得注意:
-
回调必须是同步函数。依赖收集的开启与关闭依赖
UntrackCount计数,而untrackStart/untrackEnd在同一个同步调用栈内对称执行,异步操作中的读取无法被untracked覆盖。 -
异常安全已由实现保证。
createBoundaryFunction使用try ... finally,回调抛错也会正确执行untrackEnd(),不会污染后续代码的追踪状态——因此不需要手动兜底 try/catch。 -
无参调用安全。
untracked()等价于一次空转的 start/end,可用于"占位"或条件化包装,测试用例已覆盖。 -
支持嵌套。
UntrackCount是计数器而非布尔值,多层untracked嵌套可以正常工作,最外层退出后恢复追踪。 -
读取 computed 时行为不同。如前文所述,
untracked内读取 computed 会走"直接计算"分支,若你的 computed 内部有昂贵计算且希望复用缓存,应避免在untracked中读取它。 -
可作为依赖收集的性能工具。在
autorun/reaction的追踪函数里,用untracked包裹"不参与响应"的读取(如临时中间量、仅用于分支判断的全局配置),可以减少无效依赖,避免字段频繁变化引发不必要的重执行。 -
.bound变体。从 internals.ts 的实现可以看到,untracked上还挂载了bound变体(createBindFunction),用于将回调与指定context绑定后在边界内执行;它是边界函数工厂的通用能力,需要绑定this场景时可以使用。
总结
untracked 是 @formily/reactive 响应式体系中最基础的边界原语之一:它通过 UntrackCount 计数器配合 isUntracking() 短路,在 bindTargetKeyWithCurrentReaction 这一依赖收集的唯一入口处精准拦截,实现"读取但不订阅"。它与 batch(延迟通知)正交,并与 batch 组合构成了 action 的底层实现;对 computed 则退化为"直接计算"。无论是优化 autorun 的依赖集合,还是实现只读一次的配置读取,untracked 的实现源码、边界工厂与测试用例都值得作为深入 Formily 响应式内核的第一份参考资料。