Angular Signal Forms 深入解析：`[formField]` 的编译器类型检查与 Core 运行时集成机制

本文以 Angular 仓库中 Signal Forms 的集成参考文档为主体，深入拆解 [formField] 指令是如何打通编译器与运行时的：编译器一侧通过"合成绑定展开 + 冲突检测 + 元素类型校验"实现模板级类型检查，Core 一侧通过 ɵɵcontrolCreate / ɵɵcontrol 指令与 ControlDirectiveHost 特权接口实现高效的表单状态同步。读完本文，你将理解 Signal Forms 为何被称为"单源数据绑定"，以及这套机制在 packages/compiler 与 packages/core 中的完整实现链路。

一、整体定位：一次绑定，两条执行路径

Signal Forms 的核心用法是在模板中把一个字段信号（Field<T>）直接绑到表单控件上：

<input [formField]="mySignal" />

从文档 reference-signal-forms/references/integration.md 的脉络看，这一行模板背后有两条彼此配合的技术路径：

1. 编译期（编译器集成）：packages/compiler 包中的模板类型检查逻辑识别出 formField 绑定，并将其"展开"为一组等价的原生绑定做类型验证，同时阻止开发者重复绑定同一批属性；
2. 运行期（Core 集成）：packages/core 包提供低层指令（instructions），让 FormField 指令能够绕过常规的属性绑定流程，直接读写 DOM 元素和其他指令的输入/输出，从而在不经过每个属性都走变更检测的前提下高效同步表单状态。

下面分别深入这两条路径，并给出仓库中对应的源码位置。

二、编译器集成：formField 的类型检查

编译器侧的核心逻辑位于 signal_forms.ts。这是一个 TcbOp（模板类型检查器操作），会在类型检查阶段为目标节点"合成"出验证用的 TypeScript 语句。

2.1 如何识别一个"字段指令"

类型检查器判断一个指令是否为 Signal Forms 的字段指令（Field Directive），依据在 isFieldDirective 函数中，分两条路径：

• 快速路径：指令名为 FormField，且来源模块是 @angular/forms/signals —— 覆盖所有外部用户场景；
• 慢速但更精确的路径：指令上带有 ɵNgFieldDirective 属性 —— 用于内部/本地编译场景（此时拿不到确切的模块名）。

这个 ɵNgFieldDirective 符号正是 form_field.ts 中声明的：

export const ɵNgFieldDirective: unique symbol = Symbol();

并在 FormField 类上挂载为只读属性（见 form_field.ts L372）。源码注释明确说明：之所以用符号而不是直接用内部的 ɵngControlCreate 方法作为标记，是为了避免把内部标记污染到公共 API。

2.2 合成绑定展开（Synthetic Binding Expansion）

这是编译器集成的最关键机制。当你写 <input [formField]="mySignal" /> 时，类型检查器并不止步于检查 formField 输入本身，而是合成地展开出一组绑定来验证，逻辑入口是 expandBoundAttributesForField：

• 若宿主是自定义控件且属于 value 型（有 value 输入 + valueChange 输出），则合成 [value]="mySignal().value"（双向绑定）；
• 若是 checkbox 型，则合成 [checked]="mySignal().value"；
• 此外，还会为 formControlInputFields 中列出的每一个状态字段各合成一条绑定：errors、dirty、disabled、disabledReasons、hidden、invalid、name、pending、readonly、touched、max、maxLength、min、minLength、pattern、required。

也就是说，文档中提到的 [disabled]="mySignal.disabled()"、[required]="mySignal.required()" 等并不是模板里的真实绑定，而是类型检查器在内部生成的"虚拟绑定"，用于确保 FieldNode 具备驱动表单控件所需的全部属性。值得注意的是，该字段列表被注释要求与运行时 packages/forms/signals/src/api/control.ts 中的 FormUiControl 绑定保持同步——编译期与运行期的契约是刻意对齐的。

展开时有两个细节值得注意（见 getSyntheticFieldBoundInput）：

• 主模型输入（value/checked）被标记为双向绑定（isTwoWayBinding）；
• 可选字段（max、maxLength、min、minLength，见 formControlOptionalFields）使用 SafeCall 生成展开表达式，因为它们在控件上可以缺省。

2.3 冲突检测：禁止"双重绑定"

Signal Forms 的设计前提是"信号表单控件应是唯一事实来源"。因此 TcbNativeFieldOp 维护了一个"禁绑字段"集合，包含上述全部状态字段以及 value、checked、maxlength、minlength。checkUnsupportedFieldBindings 会遍历节点上的属性绑定、静态属性和双向绑定，一旦发现禁绑字段，就通过 tcb.oobRecorder.formFieldUnsupportedBinding 记录一条编译错误。

这意味着以下写法会在编译期报错：

<!-- 错误：formField 与 value 双重绑定 -->
<input [formField]="mySignal" [value]="mySignal().value" />

一个有意思的特例是 TcbNativeRadioButtonFieldOp：单选按钮会从禁绑集合中移除 value，并额外检查 [value] 绑定必须是 string 类型（单选项的值）。

2.4 元素类型校验：信号值类型必须匹配控件类型

TcbNativeFieldOp.execute 中实现了按元素推导期望类型并生成赋值检查语句的逻辑。getExpectedTypeFromDomNode 的推导规则如下表：

宿主元素 / 输入 type	期望的信号值类型
<textarea>、<select>	string
<input type="checkbox">	boolean
<input type="radio">	string
<input type="number">、range、datetime-local	string | number | null
<input type="date" | "month" | "time" | "week">	string | number | Date | null
动态 [type] 绑定（无法静态确定）	string | number | boolean | Date | null
<input type="text"> 或未指定 type	走"不变性检查"（见下）
其他非表单原生元素	never（即不可赋值，必然报错）

其中文本类 <input> 的处理手法很巧妙（见 signal_forms.ts L140-L153）：由于 WritableSignal<T> 对 T 是不变的（invariant），类型检查器会生成一条赋值语句，把信号赋给一个 { (): string; set: (v: string) => void; } | { (): number | null; set: (v: number | null) => void; } 联合类型变量——这迫使 Field<string> 或 Field<number \| null> 精确匹配，而非通过结构子类型"宽松通过"。

对自定义控件，getCustomFieldDirectiveType 通过 hasModelInput 检测指令是否同时拥有 value/checked 输入和对应的 valueChange/checkedChange 输出，据此判定为 value 型（Form Value Control）或 checkbox 型（Form Checkbox Control）控件，再按第 2.2 节的规则做合成展开校验。另外，isNativeField 还要求节点只能是 input/select/textarea，且不存在任何自定义字段指令或形似 ControlValueAccessor（同时具备 writeValue、registerOnChange、registerOnTouched 方法）的指令，才会按原生字段路径校验。

三、Core 运行时集成：控制指令与 ControlDirectiveHost

编译器只负责"看得见"，真正让 formField 高效运转的是 packages/core 提供的低层指令与特权接口。

3.1 ɵngControlCreate 钩子与 ControlFeature 的安装

FormField 指令定义了内部方法 ɵngControlCreate(host)。编译器前端 ngtsc 会在注解解析阶段寻找该生命周期方法，提取出控制指令定义——逻辑在 shared.ts，其中还会从方法参数类型 ControlDirectiveHost<'formField'> 的泛型实参中提取 passThroughInput。

提取结果写入 R3DirectiveMetadata.controlCreate，随后在指令元数据编译时被翻译为 ɵɵControlFeature 的调用（见 compiler.ts L140-L142）。也就是说：只要一个指令声明了 ɵngControlCreate，编译器就会在生成的模板函数中安装 ɵɵControlFeature，运行时由此将其识别为"控制指令"。

3.2 ɵɵcontrolCreate 与 ɵɵcontrol 两条指令

control.ts 实现了这对指令：

• 创建阶段：ɵɵcontrolCreate 在首次创建路径（tView.firstCreatePass）中遍历节点上的指令定义，找到带 controlDef 的那个并记录 tNode.controlDirectiveIndex；随后调用 controlDef.create(instance, host)，把控制权交给 FormField 的 ɵngControlCreate。若节点上不存在控制指令（controlDirectiveIndex === -1）则直接返回，普通元素不受任何影响。
• 更新阶段：ɵɵcontrol 在更新阶段调用 controlDef.update(instance, host)，即 FormField 上由创建期选定的 ɵngControlUpdate 闭包。

模板管线侧对应的是 control_directives.ts：编译器把 controlCreate 操作插入到目标元素的创建操作之后，更新指令则由 instruction.ts 中的 control() / controlCreate() 生成对 Identifiers.control / Identifiers.controlCreate 的调用。

3.3 ControlDirectiveHost：一个"元指令"的特权接口

ɵngControlCreate 收到的 host 参数类型定义在 interfaces/control.ts，其运行时实现在 ControlDirectiveHostImpl。它赋予 FormField 四个常规指令做不到的能力：

1. 直接访问元素：nativeElement getter 通过 getNativeByTNode 拿到宿主 DOM 节点；
2. 直接写其他指令的输入：setInputOnDirectives 会遍历同一节点上的全部指令（含宿主指令的暴露输入），通过 writeToDirectiveInput 把值写入它们的输入，同时显式跳过控制指令自身以避免触发其 setter；还支持 writePredicate 按当前值决定是否写入；
3. 监听其他指令的输出：listenToCustomControlOutput / listenToCustomControlModel 借助 listenToDirectiveOutput 订阅自定义控件的 valueChange / checkedChange（模型名由 TNodeFlags.isFormValueControl 标志区分）；
4. 监听 DOM 事件：listenToDom 直接基于 listenToDomEvent 在宿主元素上注册原生事件。

从源码结构看，这套机制让 FormField 实际扮演了一个"元指令"：它替模板代管了所有属性绑定，因此模板里不再需要为 value、disabled、required 等逐个书写显式绑定语法。

3.4 创建期的分发逻辑

ɵngControlCreate 在创建期根据宿主类型选定更新策略：

• host.hasPassThrough 为真（另一指令绑定了直通输入）时直接返回；
• 存在 ControlValueAccessor 时走 cvaControlCreate（为兼容响应式表单保留）；
• 存在自定义控件（host.customControl）时走 customControlCreate；
• 是原生表单元素（<input>/<select>/<textarea> 等）时走 nativeControlCreate；
• 否则抛出 INVALID_FIELD_DIRECTIVE_HOST 运行时错误，提示宿主必须是原生表单控件或带 value/checked 模型的自定义控件。

自定义控件的识别在运行期同样基于"模型输入"约定：initializeCustomControlStatus 在首次创建路径中检查节点上的指令（以及宿主指令暴露的输入/输出），若某指令同时拥有 value 输入 + valueChange 输出则打上 isFormValueControl 标志，checked + checkedChange 则打上 isFormCheckboxControl 标志，并记录 customControlIndex。这与编译期 hasModelInput 的判定规则完全一致，形成了两端统一的"模型输入"契约。

3.5 性能语义

文档指出这一层使 FormField "能够做普通指令做不到的事"。从源码可以印证其设计取向：

• 状态同步不走模板更新函数中的属性绑定管道，而是由 controlDef.update 里的 effect 式闭包在信号变化时定向写入，避免了"每个属性都要过一遍变更检测"的开销；
• controlCreateInternal 在非控制节点上只做一次索引判断即返回，controlUpdateInternal 同样以 controlDirectiveIndex === -1 快速短路；
• 首次激活控制节点时会打 NgSignalForms 性能标记（performanceMarkFeature），便于在性能工具中观察该特性的使用。

四、端到端调用链小结

把编译期与运行期串起来，一次 <input [formField]="mySignal" /> 的完整链路是：

1. ngtsc 注解解析：在 FormField 类上发现 ɵngControlCreate，提取 controlCreate 元数据（shared.ts）；
2. 指令元数据编译：生成 ɵɵControlFeature(literal(passThroughInput)) 调用（compiler.ts）；
3. 模板管线：把 controlCreate 操作插入元素创建之后（control_directives.ts），并在更新管线中发射 control() 指令；
4. 模板类型检查：TcbNativeFieldOp 等 TCB 操作执行禁绑检查、期望类型推导与合成绑定展开（signal_forms.ts）；
5. 运行时创建：ɵɵcontrolCreate 定位 controlDirectiveIndex，调用 FormField.ɵngControlCreate，由 ControlDirectiveHostImpl 协助选定 native / custom / CVA 更新策略（control.ts）；
6. 运行时更新：信号变化触发 ɵɵcontrol → controlDef.update → 经由 setInputOnDirectives、listenToDom 等特权接口定向同步 DOM 与其他指令输入。

这套"编译器负责类型安全、Core 负责特权访问、FormField 负责策略分发"的三层结构，正是 Signal Forms 能同时做到模板零冗余、类型精确和高效更新的原因。

五、关键文件索引

关注点	文件
编译器 Signal Forms 类型检查（TcbNativeFieldOp 等）	packages/compiler/src/typecheck/ops/signal_forms.ts
控制指令元数据提取（ɵngControlCreate）	packages/compiler-cli/src/ngtsc/annotations/directive/src/shared.ts
ControlFeature 安装	packages/compiler/src/render3/view/compiler.ts
模板管线中的控制指令阶段	packages/compiler/src/template/pipeline/src/phases/control_directives.ts
ɵɵcontrolCreate / ɵɵcontrol 指令与 ControlDirectiveHostImpl	packages/core/src/render3/instructions/control.ts
ControlDirectiveDef / ControlDirectiveHost 接口定义	packages/core/src/render3/interfaces/control.ts
FormField 指令与 ɵNgFieldDirective 标记	packages/forms/signals/src/directive/form_field.ts
native / custom / CVA 三种更新策略	packages/forms/signals/src/directive/control_native.ts、control_custom.ts、control_cva.ts