前端风格指南 & 编码规范
本文档定义了 Guessimate Angular 前端的编码标准、架构模式和设计系统。
1. 技术栈
- 框架: Angular 20+
- 样式: Tailwind CSS 4
- 状态管理: Angular Signals & RxJS
- 构建系统: Angular CLI (Esbuild)
2. 项目结构
我们遵循基于特性的目录结构。代码按领域特性而非技术类型组织。
src/app/
├── core/ # 全局单例 (Guards, Interceptors, Global Services)
├── layout/ # 布局组件 (Navigation, Footer, Shell)
├── features/ # 特性模块 (领域逻辑)
│ ├── home/
│ ├── session/
│ │ ├── components/ # 无状态/展示组件
│ │ ├── pages/ # 智能/容器组件 (路由)
│ │ ├── services/ # 特性特定的状态/逻辑
│ │ └── models/ # 特性特定的类型
│ └── ...
├── websocket/ # WebSocket 基础设施
└── shared/ # 共享工具 (Pipes, Directives, Generic UI)
命名约定
- 文件: Kebab-case (例如
session-page.component.ts,auth.service.ts) - 类: PascalCase (例如
SessionPageComponent,AuthService) - 选择器:
app-前缀, kebab-case (例如app-user-profile) - Signals: 无后缀, 使用描述性名词/动词 (例如
user(),isLoading()) - Observables:
$后缀 (例如user$)
3. 组件标准
定义
- 使用独立组件 (
standalone: true在 v19+ 中为默认值) - 大多数组件优先使用内联模板,以保持逻辑和视图在同一位置
- 避免外部 CSS 文件,直接在模板中使用 Tailwind CSS 工具类
@Component({
selector: 'app-example',
imports: [CommonModule, RouterLink], // 显式导入
template: `
<div class="p-4 bg-surface-100 rounded-lg">
<h1 class="text-2xl font-bold text-gray-900">{{ title() }}</h1>
</div>
`
})
export class ExampleComponent {
title = signal('Hello World');
}
控制流
使用新的内置 Angular 控制流语法。
<!-- 推荐 -->
@if (isLoading()) {
<app-spinner/>
} @else {
@for (item of items(); track item.id) {
<app-item [data]="item"/>
}
}
依赖注入
优先使用 inject() 函数而非构造函数注入,以获得更好的类型推断和更清晰的代码。
// 推荐
private readonly
route = inject(ActivatedRoute);
private readonly
store = inject(SessionStore);
// 如果可能,避免
constructor(private
route: ActivatedRoute
)
{
}
4. 状态管理
- 本地状态: 使用
signal()处理原始状态 - 共享状态: 使用 Signal Stores (基于 Signals 的服务),在适当级别(根级或组件级)提供
- 响应式数据: 使用
computed()处理派生状态,谨慎使用effect()处理副作用
@Injectable()
export class SessionStore {
// 状态
private readonly _state = signal<SessionState>(initialState);
// 选择器
readonly lobby = computed(() => this._state().lobby);
readonly connection = computed(() => this._state().connection);
// 动作
setLobby(lobby: Lobby) {
this._state.update(s => ({...s, lobby}));
}
}
5. 样式与设计系统
我们使用 Tailwind CSS 4,并在 styles.css 中定义了语义化颜色调色板。
使用规则
- 工具优先: 直接在 HTML 中编写类
- 无魔数: 使用主题值 (例如
p-4而非p-[16px]) - 暗黑模式: 所有与颜色相关的类使用
dark:修饰符
颜色调色板
应用程序使用语义化命名约定,映射到 Tailwind 颜色。
核心颜色
| 类别 | 语义名称 | 亮色模式 | 暗色模式 | 用途 |
|---|---|---|---|---|
| 背景 | background | gray-50 | gray-950 | 应用程序主背景 |
| 表面 | surface | white | gray-900 | 卡片、模态框、段落 |
| 表面替代 | surface-alt | gray-100 | gray-800 | 次级背景、输入框 |
| 主要 | brand | blue-600 | blue-600 | 主要操作、按钮、高亮 |
| 主要淡化 | brand-muted | blue-50 | blue-900/30 | 选中状态、浅色高亮 |
| 成功 | success | emerald-500 | emerald-600 | 成功状态、确认 |
| 成功淡化 | success-muted | emerald-50 | emerald-900/30 | 成功背景 |
| 危险 | danger | red-600 | red-600 | 错误、破坏性操作 |
| 危险淡化 | danger-muted | red-50 | red-900/30 | 错误背景 |
| 警告 | warning | amber-500 | amber-600 | 警告、待处理状态 |
| 警告淡化 | warning-muted | amber-50 | amber-900/30 | 警告背景 |
排版与边框
| 类别 | 亮色模式 | 暗色模式 | 用途 |
|---|---|---|---|
| 主要 | gray-900 | white | 主要标题和正文 |
| 次要 | gray-500 | gray-400 | 副标题、标签、次要信息 |
| 淡化 | gray-400 | gray-500 | 禁用文本、占位符 |
| 边框 | gray-200 | gray-800 | 标准分隔线和卡片边框 |
styles.css 中的实现
在 @theme 块中使用 CSS 变量定义颜色:
@theme {
--color-brand-600: var(--color-blue-600);
--color-surface-100: var(--color-stone-100);
/* ... */
}
6. 常见组件模式
卡片与容器
内容容器(如估算卡、列表)的标准样式:
<div class="flex flex-col bg-surface-100/60 border border-surface-200 dark:bg-gray-900/40 dark:border-gray-800/60 rounded-md shadow-sm">
<!-- 内容 -->
</div>
- 背景:
bg-surface-100/60(亮色) /dark:bg-gray-900/40(暗色) - 边框:
border border-surface-200(亮色) /dark:border-gray-800/60(暗色) - 圆角:
rounded-md(标准) - 分隔线:
divide-y divide-surface-300 dark:divide-gray-800
排版标题
<div class="flex flex-col gap-1">
<h2 class="text-2xl font-semibold leading-none text-gray-900 dark:text-white">标题</h2>
<span class="text-sm font-normal text-gray-600 dark:text-gray-400">副标题描述</span>
</div>