8.2 KiB

Raw Blame History

🌐 Web端組件架構設計指南

📋 文檔概述

文檔名稱: Drama Ling Web端組件架構設計指南
建立日期: 2025-09-12
目標受眾: 前端工程師、UI/UX設計師、產品經理
技術基礎: HTML5 + CSS3 + Modern JavaScript

🎯 設計原則

🖥️ 桌面優先設計

多任務並行: 支援同時開啟多個學習模組
大螢幕利用: 充分使用桌面螢幕空間
快捷鍵支援: 提供完整的鍵盤操作體驗
即時回饋: 無需頁面刷新的流暢互動

📐 響應式策略

桌面優先: 1200px+ 主要設計目標
平板適配: 768px-1199px 簡化佈局
手機兼容: 320px-767px 降級體驗

🏗️ 組件架構層級

1️⃣ 佈局組件 (Layout Components)

`WebLayout_Main`

<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`

<div class="web-modal-overlay">
  <div class="web-modal-container">
    <WebModal_Header />
    <WebModal_Content />
    <WebModal_Actions />
  </div>
</div>

2️⃣ 功能組件 (Feature Components)

`WebLearning_VocabPanel`

<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`

<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`

<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端增強:

快捷鍵提示: 顯示可用快捷鍵
智能建議: 即時顯示輸入建議
多行支援: 支援長段對話輸入

📊 組件狀態管理

🔄 狀態架構

// 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
  }
}

📡 數據流向

flowchart TD
    A[用戶操作] --> B[組件事件]
    B --> C[狀態管理器]
    C --> D[API調用]
    D --> E[後端回應]
    E --> C
    C --> F[組件重渲染]
    F --> G[UI更新]

🎨 視覺設計標準

🖼️ 佈局網格

.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);
}

🎯 互動狀態

/* 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;
}

⌨️ 快捷鍵系統

🔤 全域快捷鍵

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()
}

📝 上下文快捷鍵

// 詞彙學習專用
const VocabShortcuts = {
  '←/→': () => switchWord(),
  'R': () => repeatAudio(),
  '1-4': () => selectAnswer(),
  'N': () => nextQuestion()
}

// 對話練習專用  
const DialogueShortcuts = {
  'Ctrl+H': () => showHint(),
  'Ctrl+T': () => translateMessage(),
  'Ctrl+R': () => requestAssistance()
}

🔧 開發規範

📦 組件命名

// 組件命名規範
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版結構

<!-- 手機版：單一焦點，垂直流程 -->
<div class="mobile-vocab-page">
  <header>當前: 詞彙1/5</header>
  <main>
    <div class="vocab-card">單個詞彙展示</div>
  </main>
  <footer>
    <button>上一個</button>
    <button>下一個</button>
  </footer>
</div>

💻 Web版結構

<!-- 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開發團隊

8.2 KiB Raw Blame History Unescape Escape