Formily Reactive 类型检查 API 完全指南：isObservable / isAnnotation / isSupportObservable 深入解析

前端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 响应式内核 formily/reactive 提供的三个类型检查 API——isObservable、isAnnotation与isSupportObservable。它们在响应式体系中扮演门卫角色判断一个值是否已经是可观察对象、是否携带注解标记、以及是否具备被包装为可观察对象的能力。读完本文你将理解这三个 API 的精确语义、底层实现原理、典型使用场景以及如何配合markRaw/markObservable控制哪些对象可以被响应式化。文档与源码对照本文对应的官方 API 文档位于 typeChecker.md文档给出了三个 API 的签名与功能描述。其真实实现位于 externals.ts并通过 index.ts 统一导出。在深入源码之前先回顾文档给出的 API 轮廓API签名功能isObservable(target: any): boolean判断一个对象是否已经是可观察对象isAnnotation(target: any): boolean判断一个对象是否是注解AnnotationisSupportObservable(target: any): boolean判断一个对象是否可以被包装为可观察对象isObservable判断对象是否已是响应式代理语义与签名interface isObservable { (target: any): boolean }isObservable(target)接收任意值返回boolean用于回答这个对象是否已经被 Formily 的响应式系统接管。底层实现在 externals.ts 中其实现为export const isObservable (target: any) { return ProxyRaw.has(target) || !!target?.[ObModelSymbol] }判断条件包含两个分支ProxyRaw.has(target)ProxyRaw是定义在 environment.ts 中的WeakMap保存了代理对象 → 原始对象的映射。凡是通过 Proxy 方式创建的响应式对象都会登记在该表中因此查表即可判定。target?.[ObModelSymbol]ObModelSymbolSymbol(ObModelSymbol)见 environment.ts是挂在对象上的响应式标记。像ref、computed这类盒子box对象在创建时会显式设置proxy[ObModelSymbol] store见 ref.ts、computed.ts因此无需经过 WeakMap 也能被识别。也就是说无论对象是通过observable()函数创建的 Proxy 代理还是通过注解创建的带符号标记的盒子isObservable都能准确识别。使用示例import { observable, isObservable } from formily/reactive const obs observable({ name: Formily }) console.log(isObservable(obs)) // true const plain { name: plain } console.log(isObservable(plain)) // false const boxed observable.box(1) console.log(isObservable(boxed)) // trueref/box 类型同样可被识别这一判断在 model.ts 中被用于幂等保护define()在入口处先执行if (isObservable(target)) return target避免对已响应式化的对象重复包装。isAnnotation识别响应式注解语义与签名interface isAnnotation { (target: any): boolean }isAnnotation(target)判断传入值是否为 Formily 的注解Annotation函数。注解是响应式系统用来声明如何观察某个属性的元数据例如observable.ref、observable.deep、observable.shallow、observable.computed、observable.box。底层实现在 externals.ts 中export const isAnnotation (target: any): target is Annotation { return target !!target[MakeObModelSymbol] }其原理是检查对象上是否存在MakeObModelSymbolSymbol(MakeObModelSymbol)见 environment.ts标记。查看 observable.ts 可以发现observable对象在挂载注解时统一设置了该标记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注意isAnnotation返回的是 TypeScript 类型守卫target is AnnotationAnnotation类型在 types.ts 中被定义为(...args: any[]) any。因此经过isAnnotation判定后的值在类型上可以直接作为函数使用。使用示例import { observable, isAnnotation } from formily/reactive console.log(isAnnotation(observable.ref)) // true console.log(isAnnotation(observable.computed)) // true console.log(isAnnotation(() {})) // false普通函数不是注解在 model.ts 中define()遍历用户传入的注解配置时正是用isAnnotation(annotation)过滤出合法注解再交由getObservableMaker(annotation)生成实际的观察器从而支持在类字段上按属性声明响应式策略的编程模型for (const key in annotations) { const annotation annotations[key] if (isAnnotation(annotation)) { getObservableMaker(annotation)({ target, key }) } }isSupportObservable判断值是否可被响应式化语义与签名interface isSupportObservable { (target: any): boolean }isSupportObservable(target)判断一个值是否具备被包装为可观察对象的能力。这是三者中逻辑最复杂、也最体现工程考量的 API它不仅要识别哪些类型可以观察还要主动排除哪些对象不应该被观察。底层实现完整实现位于 externals.tsexport const isSupportObservable (target: any) { if (!isValid(target)) return false if (isArr(target)) return true if (isPlainObj(target)) { if (target[RAW_TYPE]) return false if (target[OBSERVABLE_TYPE]) return true if ($$typeof in target _owner in target) return false if (target[_isAMomentObject]) return false if (target[_isJSONSchemaObject]) return false if (isFn(target[toJS])) return false if (isFn(target[toJSON])) return false return true } if (isMap(target) || isWeakMap(target) || isSet(target) || isWeakSet(target)) return true return false }可以按判断顺序拆解为五层规则1. 基础值排除if (!isValid(target)) return falseisValid定义于 checkers.ts即val ! null val ! undefined。null/undefined以及所有非引用类型的原始值数字、字符串、布尔等都无法被响应式化直接返回false。2. 数组与普通对象放行if (isArr(target)) return true if (isPlainObj(target)) { ... }数组Array.isArray无条件支持普通对象Object.prototype.toString为[object Object]进入后续黑名单检查。注意这里的isPlainObj与 checkers.ts 的定义一致只认纯对象字面量。3. 用户显式标记优先if (target[RAW_TYPE]) return false if (target[OBSERVABLE_TYPE]) return true这两个标记分别由markRaw与markObservable设置说明用户可以通过显式标记越权覆盖默认的类型推断——详见下文markRaw 与 markObservable人为控制可观察性小节。4. 框架对象黑名单if ($$typeof in target _owner in target) return false // React 元素 if (target[_isAMomentObject]) return false // moment 实例 if (target[_isJSONSchemaObject]) return false // JSON Schema 对象 if (isFn(target[toJS])) return false // MobX 等库的 toJS if (isFn(target[toJSON])) return false // 序列化对象这部分是 Formily 跨框架设计的关键体现$$typeof_owner是 React 元素ReactElement的内部标记React 元素应保持不可变不应被响应式化_isAMomentObject是 moment.js 时间对象的标记日期对象参与响应式化会引发不可预期行为_isJSONSchemaObject是 Formily 自身 json-schema 包中 JSON Schema 对象的标记Schema 元数据不应被观察具备toJS/toJSON方法的对象通常是其他库如 MobX的响应式对象或自带序列化契约的类型交由原库管理更安全。5. 集合类型放行if (isMap(target) || isWeakMap(target) || isSet(target) || isWeakSet(target)) return trueMap、WeakMap、Set、WeakSet四种集合类型均被支持这与checkers.ts中isCollectionType的判定范围一致。测试用例佐证externals.spec.ts 完整验证了上述规则expect(isSupportObservable(obs)).toBe(true) expect(isSupportObservable(new Class())).toBe(true) expect(isSupportObservable(null)).toBe(false) expect(isSupportObservable([])).toBe(true) expect(isSupportObservable({})).toBe(true) expect(isSupportObservable({ $$typeof: {}, _owner: {} })).toBe(false) expect(isSupportObservable({ _isAMomentObject: {} })).toBe(false) expect(isSupportObservable({ _isJSONSchemaObject: {} })).toBe(false) expect(isSupportObservable({ toJS: () {} })).toBe(false) expect(isSupportObservable({ toJSON: () {} })).toBe(false) expect(isSupportObservable(new Map())).toBe(true) expect(isSupportObservable(new WeakMap())).toBe(true) expect(isSupportObservable(new Set())).toBe(true) expect(isSupportObservable(new WeakSet())).toBe(true)同时在 annotations.spec.ts 中对isObservable的各种 Proxy / 盒子 / 原始对象组合进行了断言确保判断结果在不同创建路径下保持一致。使用示例import { observable, isSupportObservable } from formily/reactive isSupportObservable({ a: 1 }) // true isSupportObservable([1, 2, 3]) // true isSupportObservable(new Map()) // true isSupportObservable(null) // false isSupportObservable(div /) // falseReact 元素在 model.ts 中define()会先执行if (!isSupportObservable(target)) return target对不满足条件的对象直接原样返回避免对类实例、框架对象等做无意义的包装。markRaw 与 markObservable人为控制可观察性isSupportObservable的判定并非只能被动接受Formily 还提供了两个配套 API 让开发者主动干预markRaw(target)为对象或函数的prototype打上RAW_TYPE标记使其永远不被响应式化markObservable(target)为对象打上OBSERVABLE_TYPE标记强制其可以被响应式化。两者实现于 externals.tsexport const markRaw T(target: T): T { if (!target) return if (isFn(target)) { target.prototype[RAW_TYPE] true } else { target[RAW_TYPE] true } return target } export const markObservable T(target: T): T { if (!target) return if (isFn(target)) { target.prototype[OBSERVABLE_TYPE] true } else { target[OBSERVABLE_TYPE] true } return target }两个 API 均支持函数与普通对象两种形态传入函数时标记落在其prototype上从而对该类的所有实例生效传入对象时标记直接落在对象自身。由于isSupportObservable中 RAW_TYPE 的排除检查优先于 OBSERVABLE_TYPE 的放行检查markRaw的优先级更高——这在类实例默认被排除、个别实例被标记可观察等复杂场景下提供了清晰的裁决顺序。典型场景如果你有一个第三方类的实例Formily 默认不观察它避免误伤框架对象但你又确实需要它参与响应式可以调用markObservable(instance)显式放行反之如果某个普通对象包含不宜观察的内容如大体积二进制数据markRaw(obj)可将其永久排除在响应式系统之外。三者协同响应式系统中的门卫分工从 model.ts 中define()的实现可以清晰看到三个 API 在真实代码中的协作关系export function defineTarget extends object any( target: Target, annotations?: AnnotationsTarget ): Target { if (isObservable(target)) return target // 已响应式化则直接返回 if (!isSupportObservable(target)) return target // 不支持则原样返回 target[ObModelSymbol] target buildDataTree(undefined, undefined, target) for (const key in annotations) { const annotation annotations[key] if (isAnnotation(annotation)) { // 校验注解合法性 getObservableMaker(annotation)({ target, key }) } } return target }处理流程呈现典型的三道门卫isObservable幂等检查对象已是响应式代理 → 直接返回不做重复包装isSupportObservable资格检查对象类型不允许 / 属于框架黑名单 / 被markRaw排除 → 原样返回isAnnotation注解校验遍历注解配置时只把真正的注解函数交给getObservableMaker执行。而在model()model.ts中类字段的默认注解策略也依赖类型判断getter 属性映射为observable.computed、函数字段映射为action、其余字段映射为observable最终统一交给define()处理——这套字段类型 → 响应式策略的自动推导正是构建 Formily 表单模型FormModel / FieldModel的基础设施。总结Formily Reactive 的三个类型检查 API 构成了响应式对象的准入与识别机制isObservable通过ProxyRawWeakMap 与ObModelSymbol双重机制识别已响应式化的 Proxy 代理与盒子对象isAnnotation通过MakeObModelSymbol标记识别响应式注解函数并利用 TypeScript 类型守卫提供编译期类型收窄isSupportObservable层层过滤原始值、框架对象黑名单React 元素、moment、JSON Schema、toJS/toJSON 对象放行数组、普通对象与四种集合类型并尊重markRaw/markObservable的显式标记。这三个 API 的组合使用既保证了 Formily 在 React / React Native / Vue 2 / Vue 3 等跨框架场景下的安全响应式化也避免了库与库之间的相互干扰。若要深入理解其行为建议结合 externals.ts、model.ts 以及 externals.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 核心类型守卫指南全面解析 formily/core 的 Form Checkers 类型检查器Formily 核心类型守卫指南全面解析 formily/core 的 Form Checkers 类型检查器 本篇技术指南以 formily/core前端UI组件Formily 类型检查器完全指南深入理解 isForm、isField 与全部 is\* 系列 API 的用法与原理Formily 类型检查器完全指南深入理解 isForm、isField 与全部 is\ 系列 API 的用法与原理 Formily 的 formily/c前端UI组件Formily Form 模型完全指南formily/core 核心表单模型 API 深入解析Formily Form 模型完全指南formily/core 核心表单模型 API 深入解析 导读 Form 模型是 Formily 的核心枢纽它由 c前端UI组件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考