260 lines
5.9 KiB
Markdown
260 lines
5.9 KiB
Markdown
# 默认主题修改为浅色模式 - 设计文档
|
||
|
||
**日期：** 2026-03-06
|
||
**状态：** 已批准
|
||
**作者：** Claude Code
|
||
|
||
## 1. 概述
|
||
|
||
### 1.1 背景
|
||
|
||
当前系统默认使用深色模式侧边栏（`theme-dark`），需要将默认主题修改为浅色模式（`theme-light`）。
|
||
|
||
### 1.2 目标
|
||
|
||
- 将新用户的默认主题从深色模式改为浅色模式
|
||
- 保持老用户的自定义设置不受影响
|
||
- 确保主题切换功能完全正常
|
||
|
||
### 1.3 范围
|
||
|
||
- 仅修改前端默认配置
|
||
- 不涉及后端修改
|
||
- 不涉及数据库修改
|
||
|
||
## 2. 当前架构
|
||
|
||
### 2.1 主题配置层级
|
||
|
||
```
|
||
settings.js (默认配置)
|
||
↓
|
||
store/modules/settings.js (Vuex 状态管理)
|
||
↓
|
||
layout/components/Settings/index.vue (用户界面设置)
|
||
↓
|
||
localStorage (持久化用户设置)
|
||
```
|
||
|
||
### 2.2 主题初始化逻辑
|
||
|
||
**文件：** `ruoyi-ui/src/store/modules/settings.js`
|
||
|
||
```javascript
|
||
const storageSetting = JSON.parse(localStorage.getItem('layout-setting')) || ''
|
||
const state = {
|
||
sideTheme: storageSetting.sideTheme || sideTheme, // localStorage 优先
|
||
// ...
|
||
}
|
||
```
|
||
|
||
**逻辑：**
|
||
1. 从 `settings.js` 读取默认值
|
||
2. 检查 `localStorage` 是否有用户设置
|
||
3. 如果有用户设置，使用用户设置覆盖默认值
|
||
4. 如果没有用户设置，使用默认值
|
||
|
||
## 3. 设计方案
|
||
|
||
### 3.1 修改内容
|
||
|
||
**文件：** `ruoyi-ui/src/settings.js`
|
||
|
||
**变更：** 第 9 行
|
||
|
||
```javascript
|
||
// 修改前
|
||
sideTheme: 'theme-dark',
|
||
|
||
// 修改后
|
||
sideTheme: 'theme-light',
|
||
```
|
||
|
||
### 3.2 数据流
|
||
|
||
#### 新用户首次访问
|
||
|
||
```
|
||
用户访问系统
|
||
↓
|
||
store/modules/settings.js 初始化
|
||
↓
|
||
读取 settings.js: sideTheme = 'theme-light'
|
||
↓
|
||
检查 localStorage: 为空
|
||
↓
|
||
使用默认值: 'theme-light'
|
||
↓
|
||
渲染浅色模式侧边栏
|
||
```
|
||
|
||
#### 老用户访问（已保存设置）
|
||
|
||
```
|
||
用户访问系统
|
||
↓
|
||
store/modules/settings.js 初始化
|
||
↓
|
||
读取 settings.js: sideTheme = 'theme-light'
|
||
↓
|
||
检查 localStorage: 有值 { sideTheme: 'theme-dark' }
|
||
↓
|
||
使用 localStorage 中的值: 'theme-dark'
|
||
↓
|
||
渲染深色模式侧边栏（保持用户设置）
|
||
```
|
||
|
||
### 3.3 兼容性
|
||
|
||
**向后兼容：**
|
||
- ✅ 老用户的 localStorage 设置不受影响
|
||
- ✅ 老用户看到的主题与之前一致
|
||
|
||
**向前兼容：**
|
||
- ✅ 新用户默认看到浅色模式
|
||
- ✅ 用户仍可自由切换主题
|
||
- ✅ 保存/重置功能完全正常
|
||
|
||
## 4. 影响分析
|
||
|
||
### 4.1 影响范围
|
||
|
||
**文件变更：**
|
||
- `ruoyi-ui/src/settings.js`（1 行代码）
|
||
|
||
**功能影响：**
|
||
- ✅ 无功能变更
|
||
- ✅ 无接口变更
|
||
- ✅ 无数据结构变更
|
||
|
||
### 4.2 用户体验影响
|
||
|
||
**新用户：**
|
||
- 从深色模式默认值 → 浅色模式默认值
|
||
|
||
**老用户：**
|
||
- 无影响（localStorage 中的设置优先）
|
||
|
||
## 5. 测试计划
|
||
|
||
### 5.1 测试用例
|
||
|
||
| 测试场景 | 操作步骤 | 预期结果 |
|
||
|---------|---------|---------|
|
||
| 新用户首次访问 | 1. 清除 localStorage<br>2. 刷新页面 | 侧边栏为浅色模式 |
|
||
| 老用户（深色模式） | 1. localStorage 保存深色模式<br>2. 刷新页面 | 侧边栏仍为深色模式 |
|
||
| 老用户（浅色模式） | 1. localStorage 保存浅色模式<br>2. 刷新页面 | 侧边栏仍为浅色模式 |
|
||
| 切换主题 | 1. 打开设置抽屉<br>2. 点击深色/浅色图标 | 侧边栏立即切换 |
|
||
| 保存设置 | 1. 切换主题<br>2. 点击"保存配置"<br>3. 刷新页面 | 设置保持不变 |
|
||
| 重置设置 | 1. 修改多个设置<br>2. 点击"重置配置" | 恢复为默认值（浅色模式） |
|
||
|
||
### 5.2 浏览器兼容性
|
||
|
||
测试浏览器：
|
||
- ✅ Chrome (最新版)
|
||
- ✅ Firefox (最新版)
|
||
- ✅ Edge (最新版)
|
||
- ✅ Safari (最新版)
|
||
|
||
## 6. 部署方案
|
||
|
||
### 6.1 部署步骤
|
||
|
||
1. **修改代码**
|
||
```bash
|
||
# 修改 ruoyi-ui/src/settings.js
|
||
```
|
||
|
||
2. **提交代码**
|
||
```bash
|
||
git add ruoyi-ui/src/settings.js
|
||
git commit -m "feat: 将默认主题修改为浅色模式"
|
||
```
|
||
|
||
3. **构建前端**
|
||
```bash
|
||
cd ruoyi-ui
|
||
npm run build:prod
|
||
```
|
||
|
||
4. **部署静态资源**
|
||
- 将 `ruoyi-ui/dist/` 目录部署到生产服务器
|
||
|
||
5. **验证部署**
|
||
- 清除浏览器缓存
|
||
- 访问系统
|
||
- 验证新用户看到浅色模式
|
||
|
||
### 6.2 回滚方案
|
||
|
||
如果发现问题，可快速回滚：
|
||
|
||
```javascript
|
||
// settings.js 第 9 行
|
||
sideTheme: 'theme-dark', // 改回深色模式
|
||
```
|
||
|
||
然后重新构建和部署。
|
||
|
||
## 7. 风险评估
|
||
|
||
### 7.1 风险列表
|
||
|
||
| 风险 | 概率 | 影响 | 缓解措施 |
|
||
|-----|------|------|---------|
|
||
| 老用户困惑 | 低 | 低 | 老用户设置不受影响 |
|
||
| 浅色模式样式问题 | 低 | 中 | 需要充分测试 |
|
||
| 部署失败 | 低 | 高 | 准备回滚方案 |
|
||
|
||
### 7.2 总体风险
|
||
|
||
**风险等级：** 低
|
||
|
||
**理由：**
|
||
- 仅修改一行配置代码
|
||
- 不影响老用户设置
|
||
- 可以快速回滚
|
||
|
||
## 8. 验收标准
|
||
|
||
### 8.1 功能验收
|
||
|
||
- ✅ 新用户首次访问看到浅色模式侧边栏
|
||
- ✅ 老用户的自定义主题设置保持不变
|
||
- ✅ 主题切换功能正常
|
||
- ✅ 主题保存功能正常
|
||
- ✅ 主题重置功能正常
|
||
|
||
### 8.2 质量验收
|
||
|
||
- ✅ 代码审查通过
|
||
- ✅ 测试用例全部通过
|
||
- ✅ 无控制台错误
|
||
- ✅ 浏览器兼容性测试通过
|
||
|
||
## 9. 后续优化建议
|
||
|
||
### 9.1 短期优化
|
||
|
||
- 可以考虑在设置界面添加"推荐"标签，标注浅色模式
|
||
- 可以考虑在首次登录时提示用户可以自定义主题
|
||
|
||
### 9.2 长期优化
|
||
|
||
- 可以考虑添加更多预设主题（护眼模式、高对比度模式等）
|
||
- 可以考虑将主题设置保存到后端数据库，实现跨设备同步
|
||
|
||
## 10. 附录
|
||
|
||
### 10.1 相关文件
|
||
|
||
- `ruoyi-ui/src/settings.js` - 默认配置文件
|
||
- `ruoyi-ui/src/store/modules/settings.js` - Vuex 状态管理
|
||
- `ruoyi-ui/src/layout/components/Settings/index.vue` - 设置界面组件
|
||
- `ruoyi-ui/src/components/ThemePicker/index.vue` - 主题颜色选择器
|
||
|
||
### 10.2 参考资料
|
||
|
||
- [Element UI 主题定制](https://element.eleme.cn/#/zh-CN/theme)
|
||
- [Vuex 状态管理](https://vuex.vuejs.org/zh/)
|