342 lines
8.2 KiB
Markdown
342 lines
8.2 KiB
Markdown
# 🌐 Web端組件架構設計指南
|
||
|
||
## 📋 文檔概述
|
||
|
||
**文檔名稱**: Drama Ling Web端組件架構設計指南
|
||
**建立日期**: 2025-09-12
|
||
**目標受眾**: 前端工程師、UI/UX設計師、產品經理
|
||
**技術基礎**: HTML5 + CSS3 + Modern JavaScript
|
||
|
||
## 🎯 設計原則
|
||
|
||
### 🖥️ **桌面優先設計**
|
||
- **多任務並行**: 支援同時開啟多個學習模組
|
||
- **大螢幕利用**: 充分使用桌面螢幕空間
|
||
- **快捷鍵支援**: 提供完整的鍵盤操作體驗
|
||
- **即時回饋**: 無需頁面刷新的流暢互動
|
||
|
||
### 📐 **響應式策略**
|
||
- **桌面優先**: 1200px+ 主要設計目標
|
||
- **平板適配**: 768px-1199px 簡化佈局
|
||
- **手機兼容**: 320px-767px 降級體驗
|
||
|
||
## 🏗️ 組件架構層級
|
||
|
||
### 1️⃣ **佈局組件 (Layout Components)**
|
||
|
||
#### `WebLayout_Main`
|
||
```html
|
||
<div class="web-layout-main">
|
||
<header class="web-header">
|
||
<WebHeader_Navigation />
|
||
<WebHeader_UserStatus />
|
||
</header>
|
||
|
||
<aside class="web-sidebar">
|
||
<WebSidebar_Menu />
|
||
<WebSidebar_Progress />
|
||
</aside>
|
||
|
||
<main class="web-content">
|
||
<WebContent_Area />
|
||
</main>
|
||
</div>
|
||
```
|
||
|
||
**設計特色**:
|
||
- **固定頭部**: 命條、通知、用戶資訊常駐
|
||
- **可摺疊側邊欄**: 學習進度、快速導航
|
||
- **主內容區**: 彈性佈局，支援多視窗
|
||
|
||
#### `WebLayout_Modal`
|
||
```html
|
||
<div class="web-modal-overlay">
|
||
<div class="web-modal-container">
|
||
<WebModal_Header />
|
||
<WebModal_Content />
|
||
<WebModal_Actions />
|
||
</div>
|
||
</div>
|
||
```
|
||
|
||
### 2️⃣ **功能組件 (Feature Components)**
|
||
|
||
#### `WebLearning_VocabPanel`
|
||
```html
|
||
<div class="web-vocab-panel">
|
||
<div class="vocab-stages-overview">
|
||
<WebStage_Level1 status="completed" />
|
||
<WebStage_Level2 status="current" />
|
||
<WebStage_Level2Plus status="locked" />
|
||
<WebStage_Level3 status="locked" />
|
||
</div>
|
||
|
||
<div class="vocab-current-content">
|
||
<WebVocab_Display />
|
||
<WebVocab_AudioControls />
|
||
<WebVocab_Examples />
|
||
</div>
|
||
</div>
|
||
```
|
||
|
||
**Web端特色**:
|
||
- **四關同屏**: 同時顯示所有關卡狀態
|
||
- **即時切換**: 無縫在關卡間切換
|
||
- **詳細資訊**: 顯示更多學習數據
|
||
|
||
#### `WebLearning_DialoguePanel`
|
||
```html
|
||
<div class="web-dialogue-panel">
|
||
<div class="dialogue-character-info">
|
||
<WebCharacter_Avatar />
|
||
<WebCharacter_Details />
|
||
</div>
|
||
|
||
<div class="dialogue-conversation">
|
||
<WebDialogue_Messages />
|
||
<WebDialogue_InputArea />
|
||
</div>
|
||
|
||
<div class="dialogue-assistance">
|
||
<WebAssistance_Panel />
|
||
<WebAnalysis_Feedback />
|
||
</div>
|
||
</div>
|
||
```
|
||
|
||
### 3️⃣ **交互組件 (Interactive Components)**
|
||
|
||
#### `WebInput_Smart`
|
||
```html
|
||
<div class="web-input-smart">
|
||
<input class="smart-input-field" />
|
||
<div class="smart-suggestions">
|
||
<WebSuggestion_Item />
|
||
</div>
|
||
<div class="smart-shortcuts">
|
||
<kbd>Tab</kbd> 接受建議
|
||
<kbd>Ctrl+Enter</kbd> 送出
|
||
</div>
|
||
</div>
|
||
```
|
||
|
||
**Web端增強**:
|
||
- **快捷鍵提示**: 顯示可用快捷鍵
|
||
- **智能建議**: 即時顯示輸入建議
|
||
- **多行支援**: 支援長段對話輸入
|
||
|
||
## 📊 組件狀態管理
|
||
|
||
### 🔄 **狀態架構**
|
||
```javascript
|
||
// Web端狀態管理
|
||
const WebStateManager = {
|
||
// 學習狀態
|
||
learning: {
|
||
currentStage: 'vocab-level1',
|
||
progress: { level1: 80, level2: 60, level3: 0 },
|
||
activeWindows: ['vocab', 'dialogue']
|
||
},
|
||
|
||
// UI狀態
|
||
ui: {
|
||
sidebarCollapsed: false,
|
||
activeModals: [],
|
||
shortcuts: true,
|
||
theme: 'dark'
|
||
},
|
||
|
||
// 用戶狀態
|
||
user: {
|
||
lifePoints: 5,
|
||
diamonds: 150,
|
||
streak: 7
|
||
}
|
||
}
|
||
```
|
||
|
||
### 📡 **數據流向**
|
||
```mermaid
|
||
flowchart TD
|
||
A[用戶操作] --> B[組件事件]
|
||
B --> C[狀態管理器]
|
||
C --> D[API調用]
|
||
D --> E[後端回應]
|
||
E --> C
|
||
C --> F[組件重渲染]
|
||
F --> G[UI更新]
|
||
```
|
||
|
||
## 🎨 視覺設計標準
|
||
|
||
### 🖼️ **佈局網格**
|
||
```css
|
||
.web-container {
|
||
display: grid;
|
||
grid-template-columns: 280px 1fr; /* 側邊欄 + 主內容 */
|
||
grid-template-rows: 80px 1fr; /* 頭部 + 內容區 */
|
||
min-height: 100vh;
|
||
}
|
||
|
||
.web-content-area {
|
||
display: grid;
|
||
grid-template-columns: repeat(auto-fit, minmax(400px, 1fr));
|
||
gap: var(--space-6);
|
||
padding: var(--space-6);
|
||
}
|
||
```
|
||
|
||
### 🎯 **互動狀態**
|
||
```css
|
||
/* Web端特有的懸停效果 */
|
||
.web-interactive:hover {
|
||
transform: translateY(-2px);
|
||
box-shadow: 0 8px 25px rgba(0, 229, 204, 0.3);
|
||
transition: all 0.3s ease;
|
||
}
|
||
|
||
/* 聚焦狀態 */
|
||
.web-focusable:focus {
|
||
outline: 2px solid var(--primary-teal);
|
||
outline-offset: 2px;
|
||
}
|
||
```
|
||
|
||
## ⌨️ 快捷鍵系統
|
||
|
||
### 🔤 **全域快捷鍵**
|
||
```javascript
|
||
const WebShortcuts = {
|
||
'Ctrl+1': () => navigateToStage('vocab-level1'),
|
||
'Ctrl+2': () => navigateToStage('vocab-level2'),
|
||
'Ctrl+3': () => navigateToStage('dialogue'),
|
||
'Space': () => playAudio(),
|
||
'Ctrl+Enter': () => submitAnswer(),
|
||
'Escape': () => closeModal(),
|
||
'Ctrl+/': () => showShortcutHelp()
|
||
}
|
||
```
|
||
|
||
### 📝 **上下文快捷鍵**
|
||
```javascript
|
||
// 詞彙學習專用
|
||
const VocabShortcuts = {
|
||
'←/→': () => switchWord(),
|
||
'R': () => repeatAudio(),
|
||
'1-4': () => selectAnswer(),
|
||
'N': () => nextQuestion()
|
||
}
|
||
|
||
// 對話練習專用
|
||
const DialogueShortcuts = {
|
||
'Ctrl+H': () => showHint(),
|
||
'Ctrl+T': () => translateMessage(),
|
||
'Ctrl+R': () => requestAssistance()
|
||
}
|
||
```
|
||
|
||
## 🔧 開發規範
|
||
|
||
### 📦 **組件命名**
|
||
```javascript
|
||
// 組件命名規範
|
||
WebComponent_功能名稱 // 主要組件
|
||
WebLayout_佈局類型 // 佈局組件
|
||
WebModal_彈窗類型 // 彈窗組件
|
||
WebInput_輸入類型 // 輸入組件
|
||
```
|
||
|
||
### 🗂️ **檔案結構**
|
||
```
|
||
src/web/
|
||
├── components/
|
||
│ ├── layout/ # 佈局組件
|
||
│ │ ├── WebLayout_Main.js
|
||
│ │ └── WebLayout_Modal.js
|
||
│ ├── learning/ # 學習功能組件
|
||
│ │ ├── WebLearning_VocabPanel.js
|
||
│ │ └── WebLearning_DialoguePanel.js
|
||
│ └── common/ # 通用組件
|
||
│ ├── WebInput_Smart.js
|
||
│ └── WebButton_Action.js
|
||
├── styles/
|
||
│ ├── web-layout.scss # 佈局樣式
|
||
│ ├── web-components.scss # 組件樣式
|
||
│ └── web-responsive.scss # 響應式樣式
|
||
└── utils/
|
||
├── web-shortcuts.js # 快捷鍵管理
|
||
└── web-state.js # 狀態管理
|
||
```
|
||
|
||
## 🎮 實際範例：詞彙學習頁面
|
||
|
||
### 📱 **Mobile版結構**
|
||
```html
|
||
<!-- 手機版：單一焦點，垂直流程 -->
|
||
<div class="mobile-vocab-page">
|
||
<header>當前: 詞彙1/5</header>
|
||
<main>
|
||
<div class="vocab-card">單個詞彙展示</div>
|
||
</main>
|
||
<footer>
|
||
<button>上一個</button>
|
||
<button>下一個</button>
|
||
</footer>
|
||
</div>
|
||
```
|
||
|
||
### 💻 **Web版結構**
|
||
```html
|
||
<!-- Web版：多資訊同屏，橫向佈局 -->
|
||
<div class="web-vocab-page">
|
||
<aside class="stages-sidebar">
|
||
<div class="stage stage-completed">第1關 ✓</div>
|
||
<div class="stage stage-current">第2關 ⟲</div>
|
||
<div class="stage stage-locked">第2+關 🔒</div>
|
||
<div class="stage stage-locked">第3關 🔒</div>
|
||
</aside>
|
||
|
||
<main class="vocab-content">
|
||
<div class="vocab-overview">
|
||
<div class="vocab-list">5個詞彙預覽</div>
|
||
<div class="progress-indicator">進度: 3/5</div>
|
||
</div>
|
||
|
||
<div class="vocab-detail">
|
||
<div class="current-vocab">當前詞彙詳細資訊</div>
|
||
<div class="audio-controls">音頻控制面板</div>
|
||
<div class="examples">例句和語境</div>
|
||
</div>
|
||
</main>
|
||
|
||
<aside class="tools-panel">
|
||
<div class="shortcuts-help">快捷鍵提示</div>
|
||
<div class="statistics">學習統計</div>
|
||
</aside>
|
||
</div>
|
||
```
|
||
|
||
## 📏 響應式設計指南
|
||
|
||
### 🖥️ **桌面版** (1200px+)
|
||
- **三欄佈局**: 側邊欄 + 主內容 + 工具欄
|
||
- **豐富互動**: 懸停效果、快捷鍵提示
|
||
- **詳細資訊**: 完整統計、進度可視化
|
||
|
||
### 📱 **平板版** (768px-1199px)
|
||
- **兩欄佈局**: 可摺疊側邊欄 + 主內容
|
||
- **簡化工具欄**: 整合到主內容區
|
||
- **觸控優化**: 增大點擊區域
|
||
|
||
### 📱 **手機版** (320px-767px)
|
||
- **單欄佈局**: 全螢幕主內容
|
||
- **底部導航**: Tab式導航
|
||
- **簡化功能**: 保留核心功能
|
||
|
||
---
|
||
|
||
**維護提醒**: 當添加新的Web端功能時，請確保更新此架構文檔並遵循既定的組件設計原則。
|
||
|
||
**最後更新**: 2025-09-12
|
||
**版本**: v1.0
|
||
**維護者**: Drama Ling Web開發團隊 |