Formily Reactive 的 observable 响应式对象创建 API 全解析
前端UI组件【免费下载链接】formily Cross Device High Performance Normal Form/Dynamic(JSON Schema) Form/Form Builder -- Support React/React Native/Vue 2/Vue 3项目地址https://gitcode.com/gh_mirrors/fo/formily点击查看免费下载导读observable是 Formily 响应式核心库 formily/reactive 中最基础、使用频率最高的 API它用于创建具有不同响应式行为的对象同时也可以作为注解annotation标记类的响应式属性。本文将以 packages/reactive/docs/api/observable.md 为骨架逐一讲解observable/observable.deep、observable.shallow、observable.computed、observable.ref、observable.box五种形态的签名、适用场景与示例并结合 packages/reactive/src/observable.ts 与 packages/reactive/src/annotations 下的源码实现剖析它们各自的劫持策略与底层原理帮助你根据业务需求选择最合适的响应式容器。observable 家族概览五种形态与选择依据observable实际上是一个多态工厂它本身是函数同时又挂载了box、ref、deep、shallow、computed五个子方法。从 源码 可以看到它们之间的挂载关系export function observableT extends object(target: T): T { return createObservable(null, null, target) } observable.box annotations.box observable.ref annotations.ref observable.deep annotations.observable observable.shallow annotations.shallow observable.computed annotations.computed observable[MakeObModelSymbol] annotations.observable其中形态响应范围读写方式典型用途observable(obj)/observable.deep(obj)深劫持递归所有层级直接属性访问常规的嵌套对象 / 数组状态observable.shallow(obj)浅劫持仅第一层属性直接属性访问大数据对象只关心顶层变化observable.computed(fn)依赖追踪 缓存通过.value读取由其他响应式状态派生的计算值observable.ref(value)引用容器值整体替换通过.value读写包装基础类型number / string / booleanobservable.box(value)引用容器值整体替换通过.get()/.set()需要方法式读写的基础类型包装注意函数形式observable(obj)与observable.deep(obj)是等价的二者都指向深层劫持的注解实现见 annotations/observable.ts。deep只是语义更明确的一个别名。observable / observable.deep深层劫持响应式对象功能描述observable用于创建深层劫持的响应式对象。所谓深劫持指的是不仅目标对象自身的第一层属性是响应式的其嵌套的子对象、子数组在首次访问时也会被递归包装为响应式对象任何层级的读写操作都会被追踪和触发。签名interface observableT extends object { (target: T): T } interface deepT extends object { (target: T): T }入参为任意对象普通对象或数组返回值仍为原类型T实际返回的是原对象的响应式代理。使用示例import { observable, autorun } from formily/reactive const obs observable({ aa: { bb: 123, }, }) autorun(() { console.log(obs.aa.bb) }) obs.aa.bb 321运行上述代码时autorun中的副作用函数会立即执行一次并打印123当obs.aa.bb被修改为321时由于bb属于深层属性副作用会被重新触发并打印321。源码原理createObservable 的递归代理深层劫持的入口是 internals.ts 中的createObservable函数其核心逻辑可以归纳为三步原始值短路如果目标value不是对象typeof value ! object直接原样返回不对基础类型做包装重复包装保护通过ProxyRaw弱映射检查目标是否已被代理过若已代理则复用已有代理并维护数据树节点避免重复包装导致响应式失效构建数据树并创建代理调用buildDataTree将目标挂入全局数据树随后根据类型分别走createNormalProxy普通对象/数组走baseHandlers或createCollectionProxyMap/Set 等集合走collectionHandlers。深劫持的深体现在baseHandlers的get陷阱中当访问嵌套属性如obs.aa时如果该属性值是对象且尚未被代理处理器会递归调用createObservable将其包装后再返回。因此嵌套对象是按需惰性深度代理的——只有真正访问到的层级才会被包装这与 Vue 3 的 Proxy 实现思路一致。在tests/observable.spec.ts 中还有一组contains用例验证了深劫持下嵌套元素如arr[0].aa、element的子对象都能被数据树正确包含与追踪。observable.shallow浅层劫持响应式对象功能描述observable.shallow创建浅层劫持的响应式对象只响应目标对象第一层属性的读写操作。对于嵌套的子对象浅代理只保证替换整个子对象这一操作可被侦测子对象内部的属性变化不会被追踪。签名interface shallowT extends object { (target: T): T }使用示例import { observable, autorun } from formily/reactive const obs observable.shallow({ aa: { bb: 111, }, }) autorun(() { console.log(obs.aa.bb) }) obs.aa.bb 222 // 不会触发响应 obs.aa { bb: 333 } // 会触发响应示例中有意对比了两种写法的差异obs.aa.bb 222修改的是第二层属性浅劫持不会拦截副作用不会重新执行obs.aa { bb: 333 }替换第一层属性aa的整个引用浅劫持能够侦测到副作用重新执行。源码原理浅代理与父浅则子不代理规则浅劫持的实现位于 annotations/shallow.ts与深层实现几乎同构唯一区别是在调用createObservable(target, key, value, true)时传入第四个参数shallow true。createObservable内部由此分支见 internals.tsif (target) { const parentRaw ProxyRaw.get(target) || target const isShallowParent RawShallowProxy.get(parentRaw) if (isShallowParent) return value // 父级为浅代理时子对象不再代理原样返回 }这里有两个关键机制浅代理会通过RawShallowProxy弱映射登记见 internals.ts 中createNormalProxy/createCollectionProxy的shallow分支当某个浅代理对象的子属性被读取时baseHandlers在尝试递归代理前会先检查父级是否为浅代理——如果是则原样返回子对象不做包装。这正是obs.aa.bb 222无法触发响应的根本原因。适用建议当你的状态对象层级很深、但业务上只关心顶层结构变化时例如配置对象整体替换、列表整体更新使用shallow可以显著减少代理包装带来的开销。observable.computed带缓存的派生计算值功能描述observable.computed创建计算缓冲区calculation buffer它接受一个计算函数或包含get/set的对象返回一个带.value的响应式容器。计算值会自动追踪其内部读取的所有响应式依赖并具备惰性缓存能力依赖未变化时重复读取.value不会重复执行计算函数。签名interface computed { T extends () any(target: T): { value: ReturnTypeT } T extends { get?: () any; set?: (value: any) void }(target: T): { value: ReturnTypeT[get] } }签名支持两种重载传入纯函数{ value: ReturnTypeT }传入{ get?, set? }对象可同时定义读取逻辑与写入逻辑写入时set内部可以继续修改其他响应式状态实现可写计算属性。使用示例import { observable, autorun } from formily/reactive const obs observable({ aa: 11, bb: 22, }) const computed observable.computed(() obs.aa obs.bb) autorun(() { console.log(computed.value) }) obs.aa 33第一次读取computed.value时计算结果为3311 22并缓存当obs.aa变为33后computed 的依赖被标记为脏autorun再次读取时重新计算得到55控制台依次打印33与55。源码原理ComputedReaction 与脏标记computed 的实现是五个注解中最复杂的见 annotations/computed.ts核心可以拆解为几个部分计算反应compute()负责调用descriptor.get?.call(context)执行用户计算函数结果暂存于store.value依赖收集reaction()将自身压入ReactionStack后执行compute()这样计算函数内部读取的响应式状态就会把该反应登记为依赖reaction._name固定为ComputedReaction便于调试定位脏标记调度reaction._scheduler在依赖变化时仅置reaction._dirty true并广播计算值已过期不立即重算惰性求值get()中只有当reaction._dirty为true时才真正执行reaction()重算否则直接返回缓存的store.value读取时还会通过bindTargetKeyWithCurrentReaction把自己注册到当前正在运行的追踪者如autorun的依赖列表中批处理写入set()将descriptor.set的调用包裹在batchStart()/batchEnd()之间保证一次写入多个依赖时只触发一轮更新详见 packages/reactive/src/batch.ts。此外computed 注解在属性定义上做了性能优化getPropertyDescriptorCache会将类原型上的属性描述符按构造器缓存ClassDescriptorSymbol避免每次读取都递归遍历原型链。注意observable.computed必须与追踪上下文autorun、tracker、observe等配合使用才有意义。脱离追踪直接读取.value时由于没有消费者脏标记会在下次读取时才被重新计算即仍然正确只是不会主动求值。observable.ref引用劫持的响应式容器功能描述observable.ref创建引用劫持的响应式容器将任意值尤其是基础类型包装进一个带.value属性的容器中通过对ref.value的读写来驱动响应式更新。它解决了基础类型无法被直接代理的问题——基础类型不是对象无法挂载 getter/setter因此必须先包一层容器。签名interface refT extends object { (target: T): { value: T } }源码中的实际类型为IRefT(target: T): { value: T }见 annotations/ref.ts入参不限于objectobservable.ref(1)即传入了数字。使用示例import { observable, autorun } from formily/reactive const ref observable.ref(1) autorun(() { console.log(ref.value) }) ref.value 2控制台依次打印1与2。当ref.value被整体替换时绑定在容器上的副作用重新执行。源码原理数据树节点与响应式 value 属性ref 的实现位于 annotations/ref.ts。它创建了一个store内部存储对象并在返回的proxy上通过Object.defineProperty定义value属性的 getter/setterget()调用bindTargetKeyWithCurrentReaction把当前追踪者绑定到store.value上set(value)写入新值并在oldValue ! value时调用runReactionsFromTargetKey触发绑定在该键上的所有反应。同时它调用buildDataTree(target, key, store)将容器接入全局数据树并把proxy[ObModelSymbol] store挂上模型符号使容器与内部存储的映射关系可被框架识别。当 ref 作为类的注解使用时target/key存在会在原对象属性上直接定义 getter/setter 并返回原对象见 annotations/ref.ts。ref 与直接使用对象的区别对observable.ref(1)而言追踪的粒度是整个值而不是值的内部属性——这也正是引用劫持的含义。observable.boxget/set 方法式读写的响应式容器功能描述observable.box与observable.ref功能类似都是对基础类型等值做响应式包装区别在于box 通过get()/set()方法读写数据而不是访问.value属性。签名interface boxT extends object { (target: T): { get: () T; set: (value: T) void } }使用示例import { observable, autorun } from formily/reactive const box observable.box(1) autorun(() { console.log(box.get()) }) box.set(2)控制台依次打印1与2。源码原理显式代理映射box 的实现位于 annotations/box.ts与 ref 的关键差异在于代理的登记方式const proxy { set, get } ProxyRaw.set(proxy, store) RawProxy.set(store, proxy)ref 返回的是一个通过Object.defineProperty定义了value属性的普通proxy对象而 box 直接返回一个包含get/set方法的字面量proxy并通过ProxyRaw/RawProxy两个弱映射显式建立代理 ↔ 内部存储的双向关联。get()/set()内部同样执行依赖绑定bindTargetKeyWithCurrentReaction与变更广播runReactionsFromTargetKey并且set在值未变化时不会触发更新if (oldValue ! value)判断。当 box 作为注解使用时target存在它会用Object.defineProperty将代理对象作为不可写、不可配置的属性挂到目标上见 annotations/box.ts。作为注解使用给类属性标记响应式observable的各个形态除了直接调用还都实现了注解能力——即挂载MakeObModelSymbol标记见 internals.ts 的createAnnotation与getObservableMaker。在 TypeScript 装饰器场景下可以用它们标记类属性为响应式例如class Store { observable.ref count 0 observable.computed get double() { return this.count * 2 } }从源码看注解调用时createAnnotation会以{ target, key, value }访问器对象调用各实现target为类实例、key为属性名实现内部据此分支有target时通过Object.defineProperty定义属性并返回原对象无target时直接函数调用则创建独立容器返回详见 annotations/observable.ts 等。这就是一个 API 两种用法函数式创建 / 装饰器注解的统一入口设计。场景选型速查需求推荐 API理由管理嵌套的表单/业务对象状态observable/observable.deep深劫持任意层级读写都能触发更新对象层级深但只关心顶层替换observable.shallow减少代理开销避免不必要的深层包装由已有状态派生的值总和、过滤结果等observable.computed自动依赖追踪 惰性缓存性能最优包装数字、字符串等基础类型observable.ref属性式读写语法简洁偏好方法式读写、或需显式区分 APIobservable.boxget/set 语义明确便于封装小结observable是 formily/reactive 响应式体系的基石deep/shallow控制劫持深度computed提供依赖缓存与派生计算ref/box解决基础类型包装问题。理解它们各自的劫持粒度与底层代理/注解机制是正确使用 Formily 双向绑定、联动、校验等高级特性的前提。若想深入实践可以继续阅读 observable 的官方 API 文档并通过 observable.spec.ts 中的测试用例验证各种边界行为。赞分享前端UI组件【免费下载链接】formily Cross Device High Performance Normal Form/Dynamic(JSON Schema) Form/Form Builder -- Support React/React Native/Vue 2/Vue 3项目地址https://gitcode.com/gh_mirrors/fo/formily点击查看免费下载相关推荐formily/reactive observe API 全解析深度/浅度监听 Observable 对象的所有写操作formily/reactive observe API 全解析深度/浅度监听 Observable 对象的所有写操作 observe 是 formily前端UI组件Formily Reactive 的 raw API 详解如何从 observable 对象中取回源数据Formily Reactive 的 raw API 详解如何从 observable 对象中取回源数据 导读 raw 是 formily/reactive前端UI组件Formily Reactive 的 markRaw 详解让对象彻底脱离响应式劫持Formily Reactive 的 markRaw 详解让对象彻底脱离响应式劫持 导读 markRaw 是 formily/reactive https:前端UI组件创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

相关新闻

swagger-codegen 模型文档解析:从 ArrayOfNumberOnly 看懂“纯数字数组“模型的定义、生成与使用

swagger-codegen 模型文档解析:从 ArrayOfNumberOnly 看懂“纯数字数组“模型的定义、生成与使用

开发工具代码生成API设计 【免费下载链接】swagger-codegen swagger-codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition. 项目地址: http…

2026/11/22 8:37:40 阅读更多 →
通达信箱体主图与副图指标公式全解析:从设计思路到实战应用

通达信箱体主图与副图指标公式全解析:从设计思路到实战应用

很多年以前我刚接触通达信的时候,最痴迷的事情就是到处淘指标公式。那时候论坛里的大神们发帖都神神秘秘,动不动就是“国宝级源码”“副图之王”,下载下来一看,要么加密,要么乱码一堆,真正能看懂的没几个。…

2026/11/21 11:17:04 阅读更多 →
QLab Pro实战:用Cue列表打造稳定精确的现场演出控制中枢

QLab Pro实战:用Cue列表打造稳定精确的现场演出控制中枢

我入行做现场声音和多媒体控制这些年,设备换了一茬又一茬,但有一款软件始终待在我的骨干方案里,就是QLab Pro。它没有花哨的界面,也不是那种装上就能“自动帮你完成演出”的傻瓜工具,但它解决了一个现场工作者最头疼的…

2026/11/16 20:55:28 阅读更多 →

最新新闻

Electron桌面应用开发实战:从环境搭建到打包发布全流程

Electron桌面应用开发实战:从环境搭建到打包发布全流程

做前端这些年,我大部分时间都在跟浏览器标签页打交道,直到第一次把桌面应用跑起来,才发现原来自己一直被限制在地址栏和刷新按钮围起来的框框里。Electron这个词,最开始是在某段时间频繁出现在同事的讨论里,一个用HTML…

2026/11/21 23:27:35 阅读更多 →
滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

简介:亚太天能T109滑盖智能锁产品说明书是一份PDF格式的官方技术文档,主要面向智能锁安装人员、终端用户及售后维护者,帮助快速掌握产品安装、配置与常见故障处理。全包仅1个PDF文件,大小4.37MB,内容结构清晰&#xff…

2026/11/21 23:27:35 阅读更多 →
PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

上个月我在调试一台高速AGV的驱动系统,整车要求空载跑到8m/s,电机转速已经拉到额定点,驱动器的输出电压也顶到了母线电压极限附近。再往上踩速度指令,转速纹丝不动,三相电流反而开始震荡。那会儿我的第一反应就是&…

2026/11/21 23:27:35 阅读更多 →
C++核心知识点:从内存管理到STL的实战指南

C++核心知识点:从内存管理到STL的实战指南

C 这门语言我前前后后折腾了十几年,用它写过嵌入式驱动、做过游戏服务端,也搭过基础组件库。每次看到新人一头扎进"C 核心知识点"这个搜索词,我其实挺感慨的——这门语言的难点从来不是语法多,而是知识点之间的耦合太深…

2026/11/21 23:27:35 阅读更多 →
T109滑盖智能锁怎么装?安装调试与故障排查全攻略

T109滑盖智能锁怎么装?安装调试与故障排查全攻略

简介:亚太天能T109滑盖智能锁产品说明书以PDF格式发布,适合智能锁用户、安装人员与售后维修人员阅读。内容围绕T109系列指纹密码刷卡锁展开,先介绍前面板、后面板、锁体、机械钥匙、电池盒盖等部件名称与功能,再给出完整安装步骤&…

2026/11/21 23:27:36 阅读更多 →
LLM知识降熵:从信息垄断到理解权下放

LLM知识降熵:从信息垄断到理解权下放

你有没有过这种经历:翻开源码注释、论文摘要或者一份专业报告,每个字都认识,连在一起却像天书。想找人聊聊,身边要么没人懂,要么懂的懒得跟你解释。后来我试着把同一段内容丢给一个大语言模型,几秒钟之后&a…

2026/11/21 23:27:37 阅读更多 →

日新闻

周新闻

月新闻