SuperAPI AI 工具集

angular-personal-conventions

编程与开发

查看项目

更新于 10-22 16:17

技能介绍

用途

该技能用于在编写或审查 Angular 组件、服务、表单及异步/HTTP 数据流时,在通用现代 Angular 最佳实践之上应用一套个人编码约定。技能说明中明确要求先调用 angular-best-practices 子技能,本技能是其上的个人层,覆盖依赖注入、输入输出、表单和异步数据约定。

主要能力与规则

依赖注入:仅允许使用 inject(),禁止构造函数参数注入。若依赖被多个方法使用或需存活至构造函数之后,应赋给类顶部的 private readonly 字段;若仅在构造函数体内同步使用一次,可用局部 const 或就地内联。注意 inject() 必须在注入上下文中同步执行,不能在 RxJS 操作符回调、setTimeout 等回调内调用,需先捕获到字段或局部变量再闭包使用。

输入与输出:组件输入仅使用 input() / input.required(),禁止 @Input() 装饰器;setter 输入应改为只读 input 信号加构造函数中的 effect()。输出使用 output<T>(),禁止 @Output() + EventEmitter,emit 调用与父组件事件绑定方式不变。

组件文件结构与样式:组件文件必须拆分,*.component.ts 与 *.component.html 分离,禁止在装饰器中内联模板或样式。仅当存在工具框架无法表达的真实 CSS 时才创建 *.component.scss,不得创建空 SCSS 文件。模板样式仅使用工具类(如 Tailwind),字号、间距、颜色均通过工具类设置,组件样式中不硬编码像素值。块级组件应在 @Component 中设置 host: { class: 'block' }。程序化滚动应使用 ViewportScroller 而非原生 window.scrollTo。

异步数据:从 Observable 获取显示数据应使用 toSignal(),不要手动订阅或 effect() + subscribe()。无 initialValue 时信号类型为 T | undefined,可用于区分加载中与空结果;可在 switchMap 内用 startWith([]) 重置。takeUntilDestroyed() 仅用于不表示显示数据的命令式副作用流,OnDestroy 手动取消订阅被禁止。

响应式表单:仅使用 ReactiveFormsModule,禁止 ngModel/FormsModule(ControlValueAccessor 内部实现除外)。使用 inject(NonNullableFormBuilder) 构建,所有控件 nonNullable: true,可选字段为 T | undefined 并初始化为 undefined 而非 null。

HTTP 参数与请求体:HttpParams 不会忽略 undefined,会序列化为字符串 "undefined",应通过辅助函数过滤 undefined 后再构建。自定义 HTTP 头统一通过 HttpInterceptor 设置,头名称集中在一个共享枚举/常量中。multipart 的 FormData 应在 *.api.service.ts 方法内部组装,组件传入带类型的载荷对象,不得在组件中预构建 FormData。迁移遗留例外应标记为技术债并跟踪。

路由:使用 loadComponent 等懒加载机制,避免急切声明路由组件。

分页:卡片式列表优先使用普通分页而非无限/虚拟滚动。可复用分页控制器为普通类(非 DI 服务),内部以信号持有 items/isLoading/pageIndex/pageCount,由调用方注入依赖并传入,控制器本身不注册 DI。固定分页栏应在视口底部固定定位,列表内容预留底部内边距,仅当页数大于 1 时渲染。

布局间距:兄弟元素间距使用后一个元素的 margin-top,而非包装元素的 padding-top;组件内固定垂直堆叠使用容器 grid + gap-,而非 flex flex-col 加重复 mt-。

排版与设计比例:从设计工具移植字号/间距像素值时选择框架标准刻度上最近的类,不做缩放调整,不使用任意值类;该规则仅在应用根字号为框架默认未缩放值时成立。

Taiga UI 说明:tuiLabel 在未包裹控件时字体会自动缩小,应在全局覆盖样式中用足够具体的选择器修复,避免逐组件修补。映射为 Tailwind 类时,若令牌仅用作背景,应放在 theme.extend.backgroundColor 下而非通用颜色调色板。

日期格式化:模板中通过管道格式化日期,不要在组件类中内联 dayjs(...).format(...),格式字符串应放在使用组件自己的常量文件中。

测试注意:jsdom 与原生 fetch 存在 Blob/File 类不互通问题,可通过在受影响 spec 文件首行添加单文件环境覆盖(如 // @vitest-environment node)解决,而非全局回退环境。

使用方式

该技能以约定清单和代码对比示例呈现,规则涵盖允许与禁止的写法、代码引用路径和常见错误对照表。使用时应先加载 angular-best-practices,再将本技能作为其上层的个人约定应用。

适用场景

适用于使用 Angular 进行前端开发、需要统一依赖注入、信号输入输出、响应式表单、异步 HTTP 数据流、路由懒加载、分页和布局间距风格的团队或个人项目。

限制

该技能为个人开发者约定,部分规则依赖 Tailwind 等工具类框架和 Taiga UI 等特定组件库。技能说明指出基线测试已默认采用多数现代 Angular 惯用法,本技能主要起强化作用,异步数据流使用 toSignal() 是可靠差距点。分页偏好普通分页而非无限滚动属于经验性选择,需结合列表规模判断。技能中提及的代码引用路径属于特定项目,不保证在其它项目中存在。