# 主题系统使用指南

## 概述

项目已成功集成完整的亮色/暗色主题系统，支持一键切换并自动保存用户偏好。

## ✨ 主要特性

- ✅ 完整的亮色和暗色主题定义
- ✅ 自动检测系统主题偏好
- ✅ 用户偏好持久化（localStorage）
- ✅ 监听系统主题变化
- ✅ 平滑的过渡动画
- ✅ 50+ CSS 变量覆盖所有UI场景
- ✅ TypeScript 类型支持
- ✅ 响应式数据绑定

## 🚀 快速开始

### 1. 全局初始化（已完成）

主题系统已在 `App.vue` 中全局初始化，整个应用自动支持主题切换功能。

### 2. 主题切换按钮

在头部工具栏可以看到主题切换按钮（🌙/☀️图标），点击即可切换主题。

### 3. 手动切换主题

```typescript
import { useTheme } from '@/utils/theme';

// 在组件中使用
const { toggle, setTheme, currentTheme, isDark } = useTheme();

// 切换主题
toggle();

// 设置为特定主题
setTheme('dark'); // 或 'light'

// 获取当前主题状态
console.log(isDark()); // true 或 false
console.log(currentTheme); // 'light' 或 'dark'
```

### 4. 在样式文件中使用主题变量

```scss
.my-component {
  background: var(--background-color);
  color: var(--text-color);
  border: 1px solid var(--border-color);
  
  &:hover {
    background: var(--background-hover);
    border-color: var(--border-color-hover);
  }
}
```

## 📋 可用的 CSS 变量

### 主题标识
- `--theme-mode`: 当前主题模式 ('light' 或 'dark')

### 主要颜色
- `--primary-color`, `--primary-hover`, `--primary-active`
- `--secondary-color`, `--secondary-hover`, `--secondary-active`
- `--accent-color`, `--accent-hover`

### 背景颜色
- `--background-color`: 主要背景
- `--background-secondary`, `--background-tertiary`
- `--background-hover`

### 文本颜色
- `--text-color`: 主要文本
- `--text-secondary`, `--text-tertiary`
- `--text-inverse`: 反转文本色

### 边框颜色
- `--border-color`, `--border-color-hover`, `--border-color-active`

### 状态颜色
- `--success-color`, `--success-bg`
- `--warning-color`, `--warning-bg`
- `--error-color`, `--error-bg`
- `--info-color`, `--info-bg`

### 组件颜色
- `--card-bg`, `--card-shadow`
- `--sidebar-bg`, `--sidebar-hover`
- `--header-bg`

### 阴影
- `--shadow-sm`, `--shadow-md`, `--shadow-lg`, `--shadow-xl`

### 圆角
- `--border-radius`, `--border-radius-sm`
- `--border-radius-lg`, `--border-radius-xl`
- `--border-radius-full`

### 过渡
- `--transition-base`: all 0.3s
- `--transition-fast`: all 0.15s
- `--transition-slow`: all 0.5s

### 字体
- `--font-family-base`

## 🎨 自定义滚动条

项目已经内置了自定义滚动条样式，支持主题切换：

### 特性
- ✅ 自动适配亮色/暗色主题
- ✅ 支持 WebKit 和 Firefox 浏览器
- ✅ 平滑的过渡动画
- ✅ 悬停效果增强
- ✅ 支持隐藏滚动条（保持滚动功能）

### 滚动条大小
- 宽度/高度：8px
- 适合现代 UI 风格
- 不影响内容布局

### 使用方式

**1. 默认滚动条（自动应用）**
所有滚动容器都会自动使用主题滚动条样式。

**2. 隐藏滚动条**
如需隐藏滚动条但保持滚动功能：

```vue
<div class="scrollbar-hide">
  <!-- 内容 -->
</div>
```

**3. 自定义滚动条颜色**
如需特定区域使用不同的滚动条颜色，可在组件样式中覆盖：

```scss
.my-custom-scroll {
  &::-webkit-scrollbar-thumb {
    background: var(--primary-color);
  }
  
  scrollbar-color: var(--primary-color) var(--background-secondary);
}
```

### 浏览器兼容性
- ✅ Chrome/Edge: 完美支持
- ✅ Firefox: 完美支持
- ✅ Safari: 完美支持
- ✅ Opera: 完美支持
- ⚠️ IE: 使用原生滚动条

## 📁 文件结构

```
front/
├── src/
│   ├── App.vue                    # 全局初始化主题系统 ⭐
│   ├── main.ts                    # 入口文件，引入样式
│   ├── assets/
│   │   └── css/
│   │       ├── root.scss           # 主题变量定义
│   │       └── theme-usage.md     # 详细使用文档
│   ├── utils/
│   │   └── theme.ts               # 主题切换工具
│   ├── components/
│   │   └── ThemeToggle.vue        # 主题切换组件
│   └── views/
│       └── components/
│           └── layout.vue         # 已集成主题切换按钮
├── THEME_GUIDE.md                 # 本文件
```

## 💡 使用示例

### 示例 1: 基础组件

```vue
<template>
  <div class="card">
    <h3>{{ title }}</h3>
    <p>{{ content }}</p>
  </div>
</template>

<script setup lang="ts">
defineProps<{
  title: string;
  content: string;
}>();
</script>

<style scoped>
.card {
  background: var(--card-bg);
  color: var(--text-color);
  padding: 20px;
  border: 1px solid var(--border-color);
  border-radius: var(--border-radius-lg);
  box-shadow: var(--card-shadow);
  transition: var(--transition-base);
}

.card:hover {
  box-shadow: var(--shadow-lg);
  border-color: var(--border-color-hover);
}
</style>
```

### 示例 2: 按钮组件

```vue
<template>
  <button :class="buttonClass">
    {{ text }}
  </button>
</template>

<script setup lang="ts">
defineProps<{
  type?: 'primary' | 'secondary' | 'danger';
  text: string;
}>();

const buttonClass = computed(() => ({
  'btn-primary': true,
  [`btn-${props.type || 'primary'}`]: true,
}));
</script>

<style scoped>
button {
  padding: 8px 16px;
  border-radius: var(--border-radius);
  border: none;
  cursor: pointer;
  transition: var(--transition-fast);
  font-weight: 500;
}

.btn-primary {
  background: var(--primary-color);
  color: var(--text-inverse);
}

.btn-primary:hover {
  background: var(--primary-hover);
}

.btn-secondary {
  background: var(--secondary-color);
  color: var(--text-inverse);
}

.btn-danger {
  background: var(--error-color);
  color: var(--text-inverse);
}
</style>
```

### 示例 3: 状态提示

```vue
<template>
  <div :class="['alert', `alert-${type}`]">
    <i :class="iconClass"></i>
    <span>{{ message }}</span>
  </div>
</template>

<script setup lang="ts">
const props = defineProps<{
  type: 'success' | 'warning' | 'error' | 'info';
  message: string;
}>();

const iconClass = computed(() => {
  const icons = {
    success: 'fa-check-circle',
    warning: 'fa-exclamation-triangle',
    error: 'fa-times-circle',
    info: 'fa-info-circle',
  };
  return `fas ${icons[props.type]}`;
});
</script>

<style scoped>
.alert {
  padding: 12px 16px;
  border-radius: var(--border-radius);
  display: flex;
  align-items: center;
  gap: 8px;
}

.alert-success {
  color: var(--success-color);
  background: var(--success-bg);
}

.alert-warning {
  color: var(--warning-color);
  background: var(--warning-bg);
}

.alert-error {
  color: var(--error-color);
  background: var(--error-bg);
}

.alert-info {
  color: var(--info-color);
  background: var(--info-bg);
}
</style>
```

## 🔧 API 参考

### ThemeManager 类

```typescript
class ThemeManager {
  // 初始化主题
  init(): void;
  
  // 设置主题
  setTheme(theme: 'light' | 'dark', save?: boolean): void;
  
  // 切换主题
  toggle(): ThemeMode;
  
  // 获取当前主题
  getCurrentTheme(): ThemeMode;
  
  // 检查是否为暗色
  isDark(): boolean;
  
  // 检查是否为亮色
  isLight(): boolean;
}
```

### useTheme Hook

```typescript
export const useTheme = () => {
  return {
    currentTheme: ThemeMode;  // 当前主题
    toggle(): void;           // 切换主题
    setTheme(theme: ThemeMode): void;  // 设置主题
    isDark(): boolean;        // 是否暗色
    isLight(): boolean;       // 是否亮色
  };
};
```

## 🎨 主题配色方案

### 亮色主题
- 背景: 白色 → 浅灰
- 文本: 深灰 → 黑色
- 主色: 蓝色系 (#3498db)
- 次色: 绿色系 (#2ecc71)
- 强调: 黄色系 (#ffcc00)

### 暗色主题
- 背景: 深灰 → 黑色
- 文本: 浅灰 → 白色
- 主色: 浅蓝系 (#5dade2)
- 次色: 浅绿系 (#58d68d)
- 强调: 浅黄系 (#f7dc6f)

## 📝 注意事项

1. **始终使用 CSS 变量**: 不要在样式中硬编码颜色值
2. **响应式绑定**: 在 Vue 组件中使用 `computed` 来响应式获取主题
3. **测试两个主题**: 确保在亮色和暗色主题下都有良好的可读性
4. **避免高对比度**: 暗色主题使用柔和的色彩，减少眼部疲劳
5. **合理使用阴影**: 暗色主题中使用更深的阴影增强层次感

## 🐛 故障排除

### 主题切换不生效
- 确保在组件中正确导入并使用 `useTheme()`
- 检查是否正确添加了 `root.scss` 到主样式文件

### 样式未应用
- 确保使用 CSS 变量而不是硬编码值
- 检查元素是否正确继承了主题变量

### TypeScript 错误
- 确保已正确导入类型定义
- 重启 VS Code 的 TypeScript 服务器

## 📞 支持

如有问题或建议，请查看：
- `front/src/assets/css/theme-usage.md` - 详细使用文档
- `front/src/utils/theme.ts` - 源代码和注释
- `front/src/components/ThemeToggle.vue` - 组件示例