企业官网建设流程全解析

Bitwarden Clients Angular 组件开发规范实战指南：Standalone、Signals 与 OnPush 最佳实践

【免费下载链接】clientsBitwarden client apps (web, browser extension, desktop, and cli).项目地址: https://gitcode.com/GitHub_Trending/cl/clients

本指南基于 Bitwarden clients 开源仓库中的 .claude/rules/angular-components.md 编码规范文档，系统梳理 Angular 组件在浏览器扩展（apps/browser）、桌面应用（apps/desktop）、Web 应用（apps/web）及libs/angular等 Angular 客户端中的统一写法，涵盖 Standalone 组件、OnPush 变更检测、Signals 状态管理、RxJS 订阅约定、模板语法与迁移路径。读完本文，你将掌握这套 monorepo 中所有 Angular 组件必须遵守的编码模式，并能够看懂源码中每个@Component装饰器背后的设计约束。

适用范围与文档体系

在动手写组件之前，先要明确这套规范的作用域。.claude/rules/angular-components.md是 Bitwarden clients 仓库中供 AI 协作与开发者共同遵循的 Angular 组件级编码规则，其配套文档体系如下：

• angular.md：Angular 范围通用规则，重点是依赖注入（inject()、safeProvider()），仅适用于 Angular 代码（apps/browser、apps/desktop、apps/web、libs/angular等），在libs/common、apps/cli、SDK 等非 Angular TypeScript 中必须跳过；
• typescript.md：全 TypeScript 范围规则，包括布尔命名、禁用 TS 枚举（ADR-0025）、Observable 数据服务（ADR-0003）、文件与类命名；
• tailwind.md：Tailwind 样式规则；
• angular-modernization 技能：配套的自动化迁移工作流，详见本文末尾「迁移」小节。

这套规范的核心目标，是让分布在三个客户端应用和多个共享库中的数百个组件（仅apps/browser/src就存在大量使用ChangeDetectionStrategy.OnPush的组件）保持完全一致的技术选型与代码风格。

组件配置三原则

组件装饰器的配置遵循三条硬性规则，三者共同构成现代组件的基线形态。

1. 必须使用 Standalone 组件

所有组件必须是 standalone。NgModule 仍然可以用于分组组件，但内部的组件必须各自独立（standalone），依赖一律声明在组件装饰器的imports中，不要注册进NgModule.declarations。

以 apps/browser/src/platform/popup/layout/popup-header.component.ts 为例：

@Component({ selector: "popup-header", templateUrl: "popup-header.component.html", imports: [ NgTemplateOutlet, TypographyModule, IconButtonModule, JslibModule, AsyncActionsModule, SvgModule, ], changeDetection: ChangeDetectionStrategy.OnPush, }) export class PopupHeaderComponent { // ... }

从源码结构看，仓库中大量组件已经省略standalone: true显式声明——因为 Angular 已将 standalone 设为默认值；而迁移参考文档 migration-patterns.md 明确要求：任何仍写有standalone: false的组件都必须被迁移为 standalone。

2. 强制 OnPush 变更检测

组件必须设置changeDetection: ChangeDetectionStrategy.OnPush。这是整个仓库组件性能与可预测性的基石：OnPush 下，原地修改数组/对象（mutation）不会触发变更检测，必须创建新引用（[...arr]、{...obj}）或使用 Signals 才能驱动视图更新。

这一点在实际代码中反复出现，例如 apps/browser/src/autofill/popup/default-password-manager/default-password-manager-prompt.component.ts：

@Component({ selector: "autofill-default-password-manager-prompt", changeDetection: ChangeDetectionStrategy.OnPush, standalone: true, templateUrl: "./default-password-manager-prompt.component.html", host: { class: "tw-block tw-h-full tw-w-full", }, // imports: [...] })

3. 用host属性代替装饰器

组件级的属性与事件绑定必须写在装饰器的host属性中，而不是使用@HostBinding/@HostListener装饰器：

@Component({ selector: "app-example", changeDetection: ChangeDetectionStrategy.OnPush, imports: [CommonModule], host: { "[class.active]": "isActive()", "(click)": "onClick()", }, })

host.class这类静态类名（如上例中的tw-block tw-h-full tw-w-full）也统一放进host对象，保持装饰器内聚。

Signals 作为组件状态默认方案（ADR-0027）

Signals 是组件本地状态与模板 I/O 的默认实现，对应的架构决策记录为 ADR-0027。核心替代关系如下：

name = input<string>(""); // 可选输入，默认 "" id = input.required<string>(); // 必填输入 save = output<string>(); // 输出事件 inputEl = viewChild<ElementRef>("input"); // 查询模板引用 displayName = computed(() => `${this.firstName()} ${this.lastName()}`);

关键点在于computed()：它只在依赖变化时重新计算，优于在模板中直接调用函数（后者每次变更检测都会执行）。仓库实践中还出现了linkedSignal（见 popup-header 组件的 imports），以及用toSignal桥接服务层的 Observable 流：

import { toSignal, toObservable } from "@angular/core/rxjs-interop"; // toSignal：把 Observable 消费为信号，供模板直接调用 protected folders = toSignal(this.folderService.folderViews$, { initialValue: [] }); // toObservable：把信号暴露为流，用于跨边界集成

poup-header 组件 中toSignal的实战用法：

protected readonly vfo1Enabled = toSignal( this.configService?.getFeatureFlag$(FeatureFlag.VFO1Foundation) ?? of(false), // ... );

信号与 Observable 的分工边界

配套的 angular.md 和 SKILL.md 划清了职责：

• Signals：仅用于组件本地状态（ADR-0027）；
• Observables：用于服务层状态与跨组件通信（ADR-0003），例如 typescript.md 中的标准服务模式BehaviorSubject+asObservable()；
• 不要把服务层 Observable 转成信号存储（服务与 CLI 等非 Angular 客户端共享，必须保持 RxJS）；组件内部用toSignal()桥接即可。

订阅 Observable 的规范（ADR-0003）

服务层暴露的是 RxJS 流，组件消费时遵循以下优先级。

首选：async管道 + 新控制流

模板中优先使用async管道而非手动.subscribe()：

protected folders$ = this.folderService.folders$;

@for (folder of folders$ | async; track folder.id) { <li>{{ folder.name }}</li> }

async管道会自动完成订阅与退订，配合 OnPush 是天然组合。

必须显式订阅时：takeUntilDestroyed()

任何手动订阅都必须通过takeUntilDestroyed()管道，在组件销毁时自动取消订阅，避免内存泄漏：

// 注入上下文内（如字段初始化或 constructor） constructor() { this.observable$.pipe(takeUntilDestroyed()).subscribe(...); } // 注入上下文之外：显式传入 DestroyRef constructor(private destroyRef: DestroyRef) {} ngOnInit() { this.observable$.pipe(takeUntilDestroyed(this.destroyRef)).subscribe(...); }

这一模式在 apps/browser/src/autofill/popup/settings/autofill.component.ts 等数十个组件中均有落地（该文件含 12 处takeUntilDestroyed调用）。

禁止嵌套订阅

禁止嵌套.subscribe()调用。需要组合多个流时，使用操作符并明确选择语义：

• switchMap：取消前一个请求，适合搜索、路由参数变化；
• concatMap：严格串行、保持顺序，适合队列式任务；
• mergeMap：并行执行，谨慎使用（结果顺序不保证）。

模板编写规范

内置控制流取代结构指令

模板统一使用 Angular 内置的新控制流@if/@for/@switch，不再使用*ngIf/*ngFor/*ngSwitch：

@if (isVisible()) { <div>Content</div> } @for (item of items(); track item.id) { <div>{{ item.name }}</div> }

track表达式必须提供，让@for能高效复用 DOM 节点。迁移参考文档中给出了*ngIf/*ngFor+<ng-template>写法转换为新控制流 +@else的完整对照示例。

类与样式绑定取代 ngClass / ngStyle

优先使用原生[class.x]/[style.x]绑定，而不是ngClass/ngStyle。当类或样式数量很多时，用computed()组合派生：

<div [class.active]="isActive()" [style.width.px]="width()"></div>

需要多类名组合时，推荐在组件中先 computed 出一个对象/数组再绑定，模板保持声明式简洁。

输入与按钮的 ID 规范（QA 自动化）

每个输入框和按钮都必须有描述性 ID，供 QA 自动化定位。命名规则为：

<component_name>_<html_element>_<readable_name>

组件名与元素名之间用下划线，可读名称内部用短横线：

<input id="register-form_input_email" /> <button id="register_button_submit">Submit</button>

组件库（Bitwarden Component Library）组件可能自动生成 ID（格式<component-selector>-<n>，如bit-input-0），但必须允许外部覆盖。此外，选择器一律使用短横线（dash），不使用 camelCase。

响应式表单

必须使用**响应式表单（Reactive Forms）**而非模板驱动表单——Bitwarden 组件库就是围绕响应式表单构建的。参考 migration-patterns.md 中的典型形态：

protected formGroup = new FormGroup({ name: new FormControl("", { nonNullable: true }), email: new FormControl<string>("", { validators: [Validators.email] }), });

类编写约定

• 薄组件（Thin Components）：组件只保留视图逻辑，业务逻辑全部下沉到服务层。这是仓库可维护性的核心原则——组件职责单一、易于测试；
• 组合优先于继承：把大组件拆分为独立的 standalone 小部件。不同客户端（浏览器/桌面/Web）在页面级做定制，通过共享子组件实现复用，而不是继承一个基类；
• 成员可见性：仅被模板访问的成员用protected；组件级常量用readonly修饰；组件内部实现细节用private。

配合 angular.md 的依赖注入规范，一个现代组件的标准骨架为：

@Component({ ... }) export class MyComponent { // 1. Inputs / Outputs（signal 形式） readonly items = input<Item[]>([]); // 2. 注入依赖：inject() 而非构造函数注入 private readonly folderService = inject(FolderService); protected readonly dialogService = inject(DialogService); // 3. 模板可访问的状态 protected readonly isLoading = signal(false); protected readonly folders$ = this.folderService.folders$; // 4. 派生状态 protected readonly hasSelection = computed(() => this.selected() !== null); }

注意：依赖注入统一使用inject()函数（构造函数注入仅保留在与 CLI 等非 Angular 客户端共享的代码中）；声明 providers 时应使用@bitwarden/ui-common的safeProvider()包装，获得编译期检查（实现与抽象匹配、deps与构造函数匹配）。

枚举风格输入（Enum-Like Inputs）

Angular 模板无法直接引用 TypeScript 类型，因此当组件接受"枚举风格"的输入值时，需要把常量对象从组件中暴露出来，让模板能按名称引用成员。优先使用字符串值作为输入：

const DialogType = { Confirm: "confirm", Alert: "alert" } as const; type DialogType = (typeof DialogType)[keyof typeof DialogType]; // 数值变体需要暴露给模板绑定： protected readonly PermissionLevel = PermissionLevel;

<my-component type="alert" /> <my-component [level]="PermissionLevel.Admin" />

这与 typescript.md 的 ADR-0025「禁用 TypeScript 枚举」一脉相承：全仓库使用Object.freeze({...} as const)加派生类型别名的方式表达枚举，并配套isXxx()类型守卫、toXxx()安全转换等运行时辅助函数，实例见 libs/common/src/vault/enums/cipher-type.ts。

遗留组件迁移路线

当需要现代化改造遗留组件（NgModule → standalone、*ngIf→@if、@Input()→input()等）时，规范明确要求使用仓库自带的angular-modernization技能（SKILL.md），它按安全顺序编排迁移步骤。

第一步：优先使用 Angular CLI 自动迁移

凡是官方 CLI schematics 覆盖的场景，一律用自动迁移，禁止手写。命令全部通过npx ng执行，作用于目录（--path=<directory>）而非文件，且必须按依赖顺序执行：

# 1. Standalone：NgModule → standalone 架构 npx ng generate @angular/core:standalone --path=<directory> --mode=convert-to-standalone # 2. 控制流：*ngIf / *ngFor / *ngSwitch → @if / @for / @switch npx ng generate @angular/core:control-flow # 3. 信号输入：@Input() → signal inputs npx ng generate @angular/core:signal-input-migration # 4. 信号输出：@Output() → signal outputs npx ng generate @angular/core:output-migration # 5. 信号查询：@ViewChild / @ContentChild → signal queries npx ng generate @angular/core:signal-queries-migration # 6. inject()：构造函数注入 → inject() 函数 npx ng generate @angular/core:inject-migration # 7. 自闭合标签与清理 npx ng generate @angular/core:self-closing-tag npx ng generate @angular/core:unused-imports

第二步：应用 Bitwarden 私有模式

CLI 覆盖不了的场景按 migration-patterns.md 手动处理：

1. 添加 OnPush 变更检测（Signals 必须先落地，才能安全启用 OnPush，这是迁移顺序的关键依赖）；
2. 应用可见性修饰符（模板访问用protected，内部用private）；
3. 组件本地状态转为 Signals；
4. 服务层 Observable保持不动（不转信号）；
5. 把业务逻辑抽取到服务层（薄组件）；
6. 正确组织类成员顺序（Inputs → Outputs → Queries → 注入依赖 → 公共/受保护/私有属性 → 生命周期 → 方法）；
7. 同步更新测试以适配 standalone。

第三步：验证

npm run lint:fix # 修复 lint 与格式化 npm run test # 运行测试

必须规避的反模式

结合 migration-patterns.md 的 Anti-Patterns 清单，以下做法在合入前必须修正：

• ❌ CLI 迁移已覆盖却手动重构；
• ❌ 手动订阅却不用takeUntilDestroyed()；
• ❌ 新增 TypeScript 枚举（应使用 const 对象，ADR-0025）；
• ❌ 构造函数注入与inject()混用；
• ❌ 在共享给非 Angular 客户端的服务中使用 Signals（ADR-0003）；
• ❌ 把业务逻辑写进组件（应保持薄组件）；
• ❌ 使用effect()计算派生状态（应使用computed()）；
• ❌ 使用ngClass/ngStyle（应使用[class.*]/[style.*]）。

结语

这套规范是 Bitwarden clients 仓库 Angular 代码的"宪法"：Standalone + OnPush + Signals 构成组件基底，async管道与takeUntilDestroyed()管住订阅生命周期，新控制流与原生绑定保持模板简洁，薄组件与组合式架构保证多客户端可复用。无论你是要审查既有组件、新建弹窗页面，还是批量现代化遗留代码，都可以直接以 .claude/rules/angular-components.md 为检查清单，并参考仓库中popup-header、default-password-manager-prompt等真实组件作为落地范本。

【免费下载链接】clientsBitwarden client apps (web, browser extension, desktop, and cli).项目地址: https://gitcode.com/GitHub_Trending/cl/clients