DARK_MODE_GUIDE.md

深色模式使用指南

概述

StockRecommender 現已支援深色模式，為用戶提供在低光環境中更舒適的使用體驗。

如何使用深色模式

切換主題

1. 點擊主題切換按鈕：在應用程式標題欄右側，您會看到一個主題切換按鈕

   • 亮色模式：顯示 "🌙 深色模式" 文字
   • 深色模式：顯示 "☀️ 亮色模式" 文字

2. 鍵盤快捷方式：按鈕支援鍵盤導航

   • 使用 Tab 鍵導航至按鈕
   • 按 Enter 或 Space 鍵切換主題

主題偏好設定持久化

• 您選擇的主題將被自動儲存到瀏覽器 localStorage
• 下次訪問應用程式時，系統將自動應用您的選擇
• 若瀏覽器不支援 localStorage，應用程式將使用預設亮色模式

系統偏好設定

• 首次訪問時，如果您的作業系統設定為深色模式（macOS、Windows 11、Linux 等），應用程式可自動偵測並應用深色模式
• 您隨時可以手動切換，覆蓋系統設定

支援的功能

UI 元件

• ✅ Gradio 文字框、按鈕、下拉選單等所有標準元件
• ✅ 標題和說明文字
• ✅ 邊框和背景色
• ✅ 互動狀態（懸停、焦點）

圖表視覺化

• ✅ Plotly 長條圖
• ✅ Plotly 散布圖
• ✅ Plotly 雷達圖
• ✅ Plotly 圓餅圖
• ✅ 所有圖表文字和網格線均支援深色模式

無障礙性

• 所有主題切換功能都支援螢幕閱讀器（ARIA 標籤）
• 完全支援鍵盤導航
• 色彩對比度符合 WCAG AA 標準，確保易讀性

故障排除

深色模式無法切換

1. 清除瀏覽器快取：Ctrl+Shift+Delete（Windows）或 Cmd+Shift+Delete（Mac）
2. 關閉並重新打開瀏覽器
3. 確保 JavaScript 已啟用

localStorage 不可用

• 如果瀏覽器禁用了 localStorage，應用程式會自動回退至亮色模式
• 您可在該會話內手動切換主題，但頁面刷新後將回到預設值

色彩問題

• 確保您的瀏覽器是最新版本
• 嘗試禁用瀏覽器擴展程式（特別是深色模式相關的擴展）
• 清除 CSS 快取：在開發者工具中禁用快取並重新加載頁面

技術細節

實現方式

• CSS 變數：使用 CSS 自定義屬性 (Custom Properties) 定義主題顏色
• JavaScript 管理：ThemeManager 類別處理主題狀態和 localStorage 持久化
• Gradio 整合：通過動態 HTML 注入和 CSS 覆蓋實現 Gradio 元件的主題支援

顏色方案

亮色模式

• 背景：#ffffff（白）
• 文字：#212529（深灰）
• 主色：#1f77b4（藍）
• 強調色：#2ca02c（綠）

深色模式

• 背景：#1a1a1a（深灰）
• 文字：#e8e8e8（淺灰）
• 主色：#4a9eff（亮藍）
• 強調色：#66dd88（亮綠）

回饋和建議

如果您對深色模式有任何建議或發現問題，歡迎提交 GitHub Issue 或 Pull Request。我們期待您的反饋，以持續改進使用體驗！