angular-css-bem-best-practices

Angular + BEM CSS 最佳实践

结合 Angular 的组件架构与 BEM（Block Element Modifier）CSS 命名约定的方法指南，帮助创建可复用组件，并在前端开发中共享代码。包含 6 条规则，以及 CSS、SCSS 和 SASS 中的错误与正确示例。

适用场景

在以下情况下，请参考这些指南：

• 为 Angular 组件编写 CSS/SCSS/SASS
• 在 Angular 模板中命名 CSS 类
• 检查组件样式是否一致
• 根据样式复杂度决定是否拆分组件
• 为新的 Angular 项目设置 CSS 架构
• 重构现有样式以遵循 BEM 方法

核心原则

• 1 个组件 = 1 个 BEM 块 — 块名称与组件选择器一致
• 最多 2 层 — 仅使用 Block 和 Block__Element，绝不使用 Block__Element__SubElement
• 层级过深时拆分 — 如果需要第三层，就提取子组件
• 选择器保持扁平 — 不使用后代、子元素或带标签限定的选择器
• 采用语义化名称 — 元素名称描述 是什么，而非 如何 或 何处
• 使用修饰符表示变体 — 使用 --modifier 表示状态和变体，且始终与基础类搭配使用

按优先级划分的规则类别

优先级	规则	影响	文件
1	块 = 组件选择器	严重	bem-block-selector
2	最多 2 层嵌套	严重	bem-max-nesting
3	拆分子组件	严重	bem-split-components
4	元素命名约定	高	bem-element-naming
5	修饰符模式	高	bem-modifier-patterns
6	不使用层叠选择器	高	bem-no-cascading

快速参考

1. 块 = 组件选择器（严重）

• bem-block-selector - BEM 块名称必须与 Angular 组件选择器一致（去掉前缀）

2. 最多 2 层（严重）

• bem-max-nesting - 嵌套绝不能超过 .block__element — 不使用 .block__element__subelement

3. 拆分子组件（严重）

• bem-split-components - 当 BEM 层级将超过 2 层时，提取子组件

4. 元素命名（高）

• bem-element-naming - 为 BEM 元素使用语义明确、描述性强的 kebab-case 名称

5. 修饰符模式（高）

• bem-modifier-patterns - 配合 Angular 类绑定，正确使用 --modifier 表示状态和变体

6. 不使用层叠选择器（高）

• bem-no-cascading - 避免使用后代、子元素和带标签限定的选择器 — 让 BEM 保持扁平

BEM 速查表

.block                    → Component root (matches selector)
.block__element           → Child part of the component
.block--modifier          → Variant of the entire block
.block__element--modifier → Variant of a single element

✅ .user-card
✅ .user-card__avatar
✅ .user-card--featured
✅ .user-card__name--highlighted

❌ .user-card__header__title       (3 levels)
❌ .user-card .user-card__avatar   (descendant selector)
❌ div.user-card                   (tag-qualified)

使用方法

阅读各条规则文件，了解详细说明和代码示例：

rules/bem-block-selector.md
rules/bem-max-nesting.md
rules/bem-split-components.md
rules/bem-element-naming.md
rules/bem-modifier-patterns.md
rules/bem-no-cascading.md

每个规则文件包含：

• 简要说明规则的重要性
• 错误代码示例（CSS、SCSS、SASS）
• 正确代码示例（CSS、SCSS、SASS）
• Angular 组件集成模式
• 汇总表和参考资料

完整编译文档

如需查看包含所有详细规则的完整指南：AGENTS.md