angular-modernization

Angular 现代化

采用两步法将旧版 Angular 组件转换为现代架构：

1. 自动迁移 - 使用 Angular CLI 原理图迁移到独立组件、控制流和信号
2. Bitwarden 模式 - 符合 ADR、使用 OnPush 变更检测、正确设置可见性、保持组件精简

工作流

第 1 步：运行 Angular CLI 迁移

⚠️ 关键：只要有 Angular CLI 迁移可用，就始终使用。不要手动迁移已有 CLI 原理图支持的功能。

Angular 提供自动原理图，可处理边缘情况、更新测试并确保正确性。仅当 CLI 工具未涵盖相应模式时，才应手动迁移。

重要事项：

• 始终使用 npx ng 运行命令。
• 所有命令都必须针对目录运行，而不是文件。使用 --path 选项指定目录。
• 按顺序运行迁移（部分迁移依赖其他迁移）

1. 独立组件

npx ng generate @angular/core:standalone --path=<directory> --mode=convert-to-standalone

基于 NgModule 的架构 → 独立组件架构

2. 控制流语法

npx ng generate @angular/core:control-flow

*ngIf、*ngFor、*ngSwitch → @if、@for、@switch

3. 信号输入

npx ng generate @angular/core:signal-input-migration

@Input() → 信号输入

4. 信号输出

npx ng generate @angular/core:output-migration

@Output() → 信号输出

5. 信号查询

npx ng generate @angular/core:signal-queries-migration

@ViewChild、@ContentChild 等 → 信号查询

6. inject() 函数

npx ng generate @angular/core:inject-migration

构造函数注入 → inject() 函数

7. 自闭合标签

npx ng generate @angular/core:self-closing-tag

将模板更新为自闭合语法

8. 未使用的导入

npx ng generate @angular/core:unused-imports

移除未使用的导入

第 2 步：应用 Bitwarden 模式

详细示例请参阅 migration-patterns.md。

1. 添加 OnPush 变更检测
2. 应用可见性修饰符（模板可访问的成员使用 protected，内部成员使用 private）
3. 将组件本地状态转换为信号
4. 保留服务可观察对象（不要将其转换为信号）
5. 将业务逻辑提取到服务中
6. 正确组织类成员
7. 更新独立组件的测试

第 3 步：验证

• 使用 npm run lint:fix 修复 lint 和格式问题
• 使用 npm run test 运行测试

如果出现错误，请相应地修复。

关键决策

信号与可观察对象

• 信号 - 仅用于组件本地状态（ADR-0027）
• 可观察对象 - 用于服务状态和组件间通信（ADR-0003）
• 使用 toSignal() 将可观察对象接入基于信号的组件

可见性

• protected - 可由模板访问的成员
• private - 内部实现

其他规则

• 始终添加 OnPush 变更检测
• 不使用 TypeScript 枚举（根据 ADR-0025，使用带类型别名的 const 对象）
• 不使用代码区域（应进行重构）
• 保持组件精简（将业务逻辑放在服务中）

验证清单

完成迁移前：

• 已添加 OnPush 变更检测
• 已应用可见性修饰符（protected/private）
• 组件状态使用信号，服务状态使用可观察对象
• 已组织类成员（参见 migration-patterns.md）
• 已更新测试且测试通过
• 未新增 TypeScript 枚举
• 未使用代码区域

参考资料

Bitwarden ADR

• ADR-0003：可观察数据服务
• ADR-0025：不使用 TypeScript 枚举
• ADR-0027：Angular 信号
• Bitwarden Angular 风格指南

Angular 资源

• Angular 风格指南
• Angular 迁移
• Angular CLI 原理图