SuperAPI AI 工具集

reference-signal-forms

前端与建站

查看项目

更新于 10-16 01:15

技能介绍

用途:该技能用于说明 packages/forms/signals 目录下 Angular 实验性信号表单 API 的心智模型与架构,适用于需要阅读、理解或改动该目录代码的场景,官方要求任何涉及该代码的工作都必须使用本技能。

主要心智模型:一是模型驱动,系统围绕 WritableSignal<T> 构建,信号本身是唯一数据源,表单只是该信号的视图或投影,附加有效性、dirty、touched 等表单状态,这点与由 FormControl 持有值的 Reactive Forms 不同。二是基于 Proxy 的遍历,form(signal) 返回 FieldTree,该对象是 Proxy,可直接访问嵌套字段(如 myForm.user.name),访问属性时懒解析或创建对应的 FieldNode,无需手动建立 control group。三是基于 Schema 的逻辑,校验、禁用状态等元数据通过 Schema 单独定义,用 apply、applyEach(数组)、applyWhen 应用到表单结构,从而把数据结构与规则分离。四是指令作为胶水,[formField] 指令把 DOM 元素(原生 input 或自定义控件)绑定到 FieldNode,负责 DOM 与信号之间的值同步、把 valid、touched 等状态反映到 UI,以及处理 blur、input 等交互事件。

关键组件:FieldNode(src/field/node.ts)是表单图中单个字段的核心内部类,聚合 structure(父子关系与信号切片)、validationState(valid、invalid、errors)、nodeState(touched、dirty、pristine)、metadataState(min、max、required 等元数据)、submitState(提交状态与服务端错误)。ValidationState(src/field/validation.ts)处理同步错误、异步错误(含 pending 状态)、树错误(冒泡或指向特定字段的错误)以及通过 submit() 注入的服务端提交错误。FormField 指令(src/directive/form_field_directive.ts)选择器为 [formField],支持原生 input、select、textarea,支持实现 FormUiControl 或 FormValueControl 的自定义控件,并可通过 InteropNgControl 兼容实现 ControlValueAccessor 的旧式组件。Schema 定义在 src/api/structure.ts 与 src/api/rules,通过 schema(fn) 创建,包含校验器(required、pattern、min、max)和状态修饰符(disabled、hidden)。

数据流:读取时 form.field.value() 直接从底层信号(按路径投影)读取;写入时更新底层信号;校验由 computed effect 观察值信号并运行 Schema 中定义的校验器。

概念用法:先定义模型 const user = signal({name: '', age: 0}),再定义 Schema const userRules = schema((u) => { required(u.name); min(u.age, 18); }),然后创建表单 const userForm = form(user, userRules) 或 apply(userForm, userRules),最后在模板中绑定 <input [formField]="userForm.name">。

重要文件:packages/forms/signals/src/api/structure.ts(公开 API 入口 form、apply)、src/api/control.ts(自定义控件接口 FormUiControl)、src/field/node.ts(FieldNode 实现)、src/directive/form_field_directive.ts([formField] 指令)。资料还提及补充信息:编译器与核心集成,说明 [formField] 如何接入类型检查与运行时。

限制:资料明确指出这是实验性 API,与现有 Reactive 和 Template-driven forms 差异显著;未提供版本、稳定性、性能、浏览器支持、安装方式及完整代码示例,这些方面暂未提供。