119 lines
3.2 KiB
Markdown
119 lines
3.2 KiB
Markdown
# 暗色模式模块
|
||
|
||
## 概述
|
||
追光AI支持浅色/暗色双主题模式，通过 ThemeProvider + CSS 变量驱动，用户偏好自动持久化到 localStorage，整体遵循 Tailwind CSS `class` 策略。
|
||
|
||
## 架构
|
||
|
||
```
|
||
ThemeProvider (Context)
|
||
├── 读取 localStorage 初始主题
|
||
├── 监听系统 prefers-color-scheme 变化
|
||
├── 在 <html> 上切换 "dark" class
|
||
└── 提供 toggle/setTheme 方法给子孙组件
|
||
```
|
||
|
||
---
|
||
|
||
## 核心组件
|
||
|
||
### ThemeProvider
|
||
- **文件**: `src/components/ThemeProvider.tsx`
|
||
- **位置**: 根 layout.tsx 包裹
|
||
- **功能**:
|
||
- `theme` state: `"light"` | `"dark"` | `"system"`
|
||
- `toggleTheme()` — 在 light/dark 间切换
|
||
- `setTheme(mode)` — 设置为指定模式
|
||
- 自动监听 `prefers-color-scheme` 媒体查询（`system` 模式时）
|
||
- 持久化到 `localStorage("zhuiguang-theme")`
|
||
|
||
### Header 主题切换按钮
|
||
- **文件**: `src/components/layout/Header.tsx`
|
||
- 太阳 ☀️ / 月亮 🌙 图标切换
|
||
- 点击调用 `toggleTheme()`
|
||
- 动画过渡效果
|
||
|
||
---
|
||
|
||
## CSS 变量系统
|
||
|
||
### globals.css 暗色变量
|
||
```css
|
||
:root {
|
||
/* 浅色主题变量 (默认) */
|
||
--background: 0 0% 100%;
|
||
--foreground: 222 47% 11%;
|
||
/* ... */
|
||
}
|
||
|
||
.dark {
|
||
/* 暗色主题变量覆盖 */
|
||
--background: 222 47% 11%;
|
||
--foreground: 210 40% 98%;
|
||
/* ... */
|
||
}
|
||
```
|
||
|
||
- 使用 HSL 变量，Tailwind 通过 `hsl(var(--xxx))` 引用
|
||
- shadcn/ui 组件自动适配暗色模式（基于 `.dark` class）
|
||
|
||
---
|
||
|
||
## 组件适配（14个文件已更新）
|
||
|
||
以下组件已适配暗色模式：
|
||
|
||
| 组件 | 适配内容 |
|
||
|------|----------|
|
||
| Header | 主题切换按钮、导航栏背景色 |
|
||
| Footer | 页脚背景色、文字色、分隔线 |
|
||
| HeroBanner | Canvas 粒子颜色随主题切换 |
|
||
| HomePageClient | 卡片背景、文字颜色 |
|
||
| ToolsContent | 搜索框、筛选侧边栏、卡片 |
|
||
| SkillsPageClient | 技能卡片、分类标签 |
|
||
| 社区相关组件 | ForumBoard/ForumTopicCard/ForumEditor |
|
||
| 通知组件 | NotificationBell/NotificationCenter |
|
||
| 用户中心 | 积分卡片、等级进度条 |
|
||
| 工具详情 | 信息面板、推荐列表 |
|
||
| 技能详情 | 评测卡片、详情面板 |
|
||
| 后台管理 | 管理面板所有表格/表单 |
|
||
|
||
---
|
||
|
||
## 设计规范
|
||
|
||
### 浅色主题
|
||
- 背景: `bg-white` / `bg-muted/50`
|
||
- 卡片: `bg-white/80` (毛玻璃) / `bg-white/60` (卡片)
|
||
- 边框: `border-border/40`
|
||
- 阴影: `shadow-sm`
|
||
|
||
### 暗色主题
|
||
- 背景: `bg-background` (HSL 222 47% 11%)
|
||
- 卡片: `bg-card` (HSL 222 47% 13-15%)
|
||
- 边框: `border-border` (HSL 215 20% 25%)
|
||
- 阴影: `shadow-md` (更明显的阴影)
|
||
|
||
### 颜色规范（双主题通用）
|
||
- 文字: 浅色 `-600/-700` | 暗色 `-300/-200`
|
||
- 背景: 浅色 `-50` | 暗色 `-900/-950`
|
||
- 边框: 浅色 `-200/60` | 暗色 `-700/60`
|
||
|
||
---
|
||
|
||
## 技术实现要点
|
||
|
||
### 闪烁防护
|
||
- ThemeProvider 在 `useEffect` 中初始化，避免 SSR 时的主题闪烁
|
||
- `<html>` 上通过内联 script 在 hydration 前设置 class（防止白屏闪烁）
|
||
|
||
### 系统主题跟随
|
||
- `matchMedia('(prefers-color-scheme: dark)')` 监听
|
||
- 用户手动设置后覆盖系统偏好
|
||
- "system" 模式时动态跟随
|
||
|
||
### 持久化策略
|
||
- 存储键: `zhuiguang-theme`
|
||
- 值: `"light"` | `"dark"`
|
||
- 优先级: localStorage > 系统偏好 > 默认 light
|