主題系統開發指南

系統概述

本系統實現了企業級的主題切換與視覺效果管理，包含 6 種專業主題、即時性能監控和專業開發工具。

核心特性

• 6 種專業主題: Classic、Soft、Corporate、Dark、Glassmorphism、Neon
• 4 種視覺效果: 玻璃液態、霓虹發光、液態漸變、噪點紋理
• 即時性能監控: 渲染時間、FPS、複雜度三重指標
• 開發工具整合: CSS 變數檢查器、效果強度控制、ThemeTester 路由

架構設計

主要組件結構

src/
├── composables/
│   └── useTheme.ts           # 主題管理核心 composable
├── components/
│   ├── DevFloatingWidget.vue # 主題開發控制面板
│   └── ThemeTester.vue      # 完整主題測試器 (25+ 組件)
├── styles/
│   ├── main.scss            # 主題切換動畫與全域樣式
│   ├── mixins/              # SCSS mixins 庫
│   │   ├── glass-mixins.scss
│   │   ├── gradient-mixins.scss
│   │   └── neon-mixins.scss
│   └── effects/             # 視覺效果實現
│       ├── glassmorphism.scss
│       ├── fluid-gradients.scss
│       ├── neon-glow.scss
│       └── noise-texture.scss
└── router/
    └── index.ts             # ThemeTester 路由配置

系統架構流程

用戶切換主題 → useTheme.ts → CSS 變數更新 → 視覺效果觸發 → 性能監控
     ↓              ↓              ↓              ↓            ↓
DevFloatingWidget → applyTheme() → DOM 樣式更新 → 效果渲染 → 指標計算

主題配置系統

ThemeConfig 介面定義

export interface ThemeConfig {
  name: string              // 主題名稱
  description: string       // 主題說明
  features: string[]        // 主要特色 (Badge 顯示)
  bestFor: string[]         // 適用場景
  preview: string          // 預覽圖示 emoji
  category: 'classic' | 'modern' | 'experimental'
  tokens: {                // CSS 變數配置
    primary: string
    primaryRgb: string
    secondary: string
    // ... 完整色彩系統
  }
  effects: {               // 視覺效果開關
    glassmorphism: boolean
    neonGlow: boolean
    fluidGradients: boolean
    noiseTexture: boolean
  }
}

主題配置範例

const themes: Record<string, ThemeConfig> = {
  glassmorphism: {
    name: '玻璃液態',
    description: '現代玻璃效果，營造輕盈透明感',
    features: ['毛玻璃效果', '背景模糊', '透明層次'],
    bestFor: ['現代介面', '輕量設計', '時尚應用'],
    preview: '🌊',
    category: 'modern',
    tokens: {
      primary: '65 105 225',
      background: '255 255 255',
      // ...
    },
    effects: {
      glassmorphism: true,
      neonGlow: false,
      fluidGradients: true,
      noiseTexture: false
    }
  }
}

🎛️ DevFloatingWidget 功能詳解

1. CSS 變數檢查器 💾

功能: 即時監控當前主題的所有 CSS 變數

const currentCSSVars = computed(() => {
  const style = getComputedStyle(document.documentElement)
  const themeVars = [
    '--primary', '--primary-rgb', '--primary-foreground',
    '--secondary', '--background', '--card', '--border'
    // ... 完整變數清單
  ]
  
  return themeVars.map(varName => ({
    name: varName,
    value: style.getPropertyValue(varName).trim(),
    type: isColorVar(varName) ? 'color' : 'other'
  }))
})

特色:

• ✅ 色彩變數提供色塊預覽
• ✅ 一鍵複製變數值 (📋 圖示)
• ✅ 自動分類色彩與其他變數

2. 效果強度控制滑桿 🎛️

功能: 即時調整視覺效果強度

const effectIntensity = ref({
  glass: 1.0,    // 玻璃效果: 0-1
  neon: 1.0,     // 霓虹發光: 0-2  
  fluid: 1.0,    // 液態動畫: 0.5-3x
  noise: 1.0     // 噪點紋理: 0-1
})

const updateEffectIntensity = () => {
  Object.entries(effectIntensity.value).forEach(([effect, intensity]) => {
    document.documentElement.style.setProperty(`--${effect}-intensity`, intensity.toString())
  })
  // 同步更新性能指標
}

互動體驗:

• ✅ 拖拽滑桿立即預覽效果
• ✅ 數值即時顯示
• ✅ 一鍵重置預設值

3. 性能監控系統 📊

指標定義

指標	定義	評級標準	用途
渲染時間	主題切換至 DOM 更新完成時間	≤16ms(優秀) 17-33ms(普通) >33ms(需優化)	評估切換響應速度
FPS	每秒畫面更新次數	≥60fps(流暢) 30-59fps(可用) <30fps(卡頓)	監控動畫流暢度
複雜度	基於效果強度的視覺負載等級	Low/Medium/High	性能預警

測試架構 (3 階段)

const startPerformanceTest = async () => {
  // Phase 1: 基準測試
  const baselineStart = performance.now()
  await new Promise(resolve => requestAnimationFrame(resolve))
  
  // Phase 2: 主題切換測試 (模擬 3 次隨機切換)
  for (let i = 0; i < 3; i++) {
    const randomTheme = themes[Math.floor(Math.random() * themes.length)]
    await new Promise(resolve => setTimeout(resolve, 100))
    // 模擬DOM重繪
  }
  
  // Phase 3: FPS 測試 (1 秒內幀數統計)
  let frameCount = 0
  const countFrames = () => {
    frameCount++
    if (performance.now() - fpsStart < 1000) {
      requestAnimationFrame(countFrames)
    }
  }
  
  // 計算結果與智能建議
}

智能建議系統

// 根據測試結果提供優化建議
if (renderTime > 33) return "建議降低效果強度以提升性能"
if (fps < 30) return "檢測到低幀率，可能需優化動畫"  
return "性能表現良好！"

🔄 主題切換動畫系統

CSS 過渡動畫

// 主題切換時的平滑過渡
.theme-transitioning {
  * {
    transition: 
      background-color 0.3s cubic-bezier(0.4, 0, 0.2, 1),
      border-color 0.3s cubic-bezier(0.4, 0, 0.2, 1),
      color 0.3s cubic-bezier(0.4, 0, 0.2, 1),
      box-shadow 0.3s cubic-bezier(0.4, 0, 0.2, 1) !important;
  }
}

動畫觸發流程

const applyTheme = (theme: ThemeConfig) => {
  const body = document.body
  
  // 1. 添加過渡動畫類別
  body.classList.add('theme-transitioning')
  
  // 2. 應用 CSS 變數
  Object.entries(theme.tokens).forEach(([key, value]) => {
    document.documentElement.style.setProperty(`--${key}`, value)
  })
  
  // 3. Toast 回饋
  toastHelper.success(`已切換至「${theme.name}」主題`)
  
  // 4. 300ms 後移除過渡類別
  setTimeout(() => {
    body.classList.remove('theme-transitioning')
  }, 300)
}

🧪 測試與驗證

ThemeTester 整合

• 路由配置: /theme-tester 路由已配置
• 組件數量: 25+ UI 組件完整測試
• 跳轉機制: DevFloatingWidget 「🎨 完整測試器」按鈕

響應式適配

@media (max-width: 768px) {
  .glass-effect,
  .neon-glow,
  .fluid-gradient {
    filter: brightness(0.9); // 降低效果強度
  }
}

@media (prefers-reduced-motion: reduce) {
  .fluid-gradient,
  .morphing-gradient {
    animation: none !important; // 停用動畫
  }
}

📈 效能優化策略

1. 懶載入策略

• CSS 效果按需載入
• 主題資源動態載入
• 組件按需渲染

2. 快取機制

• CSS 變數結果快取
• 性能測試結果快取
• 主題配置快取

3. 性能監控

• 即時渲染時間追蹤
• FPS 持續監控
• 記憶體使用量評估

未來擴展規劃

Phase 1: 主題管理增強

• [ ] 主題預設保存功能
• [ ] 自定義主題建立器
• [ ] 主題匯出/匯入功能

Phase 2: 性能優化

• [ ] 更精確的性能基準測試
• [ ] 不同設備性能適配
• [ ] A/B 測試框架整合

Phase 3: 開發工具擴展

• [ ] 主題除錯面板
• [ ] 視覺回歸測試
• [ ] 自動化主題生成

🎓 開發最佳實踐

1. 主題開發流程

1. 設計階段: 確定色彩系統和視覺風格
2. 配置階段: 建立 ThemeConfig 物件
3. 效果階段: 選擇和配置視覺效果
4. 測試階段: 使用 ThemeTester 全面測試
5. 性能階段: 執行性能測試並優化

2. 代碼規範

• 所有主題配置集中在 useTheme.ts
• CSS 變數命名遵循 --{category}-{property} 格式
• 視覺效果使用 SCSS mixins 實現
• 性能關鍵路徑避免不必要的計算

3. 測試策略

• 每個主題都需通過 ThemeTester 測試
• 性能測試結果需符合基準要求
• 響應式設計在多設備測試
• 無障礙設計驗證

故障排除指南

常見問題

1. 主題切換無效果: 檢查 CSS 變數是否正確設置
2. 性能測試失敗: 確認 performance.now() 支援
3. 效果強度無變化: 檢查 CSS 變數綁定
4. 路由跳轉失敗: 確認路由配置正確

除錯工具

• DevTools Console: 查看主題切換日誌
• CSS Variables Inspector: 即時檢查變數值
• Performance Monitor: 查看性能指標
• Network Tab: 檢查資源載入

---

最後更新: 2025-08-29
版本: 1.0.0