前端風格指南與編碼慣例
本文件定義了 Guessimate Angular 前端專案的編碼標準、架構模式以及設計系統。
1. 技術棧
- 框架: Angular 20+
- 樣式: Tailwind CSS 4
- 狀態管理: Angular Signals 與 RxJS
- 建置系統: Angular CLI (Esbuild)
2. 專案結構
我們採用基於功能(Feature-Based) 的目錄結構。程式碼按照領域功能而非技術類型組織。
src/app/
├── core/ # 全域單例 (Guards、Interceptors、全域服務)
├── layout/ # 佈局元件 (導航列、頁尾、外殼)
├── features/ # 功能模組 (領域邏輯)
│ ├── home/
│ ├── session/
│ │ ├── components/ # 無狀態/展現元件
│ │ ├── pages/ # 智慧/容器元件 (路由化)
│ │ ├── services/ # 功能專屬的狀態/邏輯
│ │ └── models/ # 功能專屬的型別
│ └── ...
├── websocket/ # WebSocket 基礎設施
└── shared/ # 共用工具 (Pipe、Directive、通用 UI)
命名慣例
- 檔案: 短橫線式 (kebab-case) (例如
session-page.component.ts、auth.service.ts)。 - 類別: 大駝峰式 (PascalCase) (例如
SessionPageComponent、AuthService)。 - 選擇器: 以
app-為前綴,短橫線式 (例如app-user-profile)。 - Signal: 無後綴,使用描述性的名詞/動詞 (例如
user()、isLoading())。 - Observable: 使用
$後綴 (例如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 (使用 Signal 的服務),並在適當層級 (根層級或元件層級) 提供。
- 反應式資料: 對衍生狀態使用
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>