5.9 KiB
5.9 KiB
默认主题修改为浅色模式 - 设计文档
日期： 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
const storageSetting = JSON.parse(localStorage.getItem('layout-setting')) || ''
const state = {
sideTheme: storageSetting.sideTheme || sideTheme, // localStorage 优先
// ...
}
逻辑：
- 从
settings.js读取默认值 - 检查
localStorage是否有用户设置 - 如果有用户设置，使用用户设置覆盖默认值
- 如果没有用户设置，使用默认值
3. 设计方案
3.1 修改内容
文件： ruoyi-ui/src/settings.js
变更： 第 9 行
// 修改前
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 2. 刷新页面 |
侧边栏为浅色模式 |
| 老用户（深色模式） | 1. localStorage 保存深色模式 2. 刷新页面 |
侧边栏仍为深色模式 |
| 老用户（浅色模式） | 1. localStorage 保存浅色模式 2. 刷新页面 |
侧边栏仍为浅色模式 |
| 切换主题 | 1. 打开设置抽屉 2. 点击深色/浅色图标 |
侧边栏立即切换 |
| 保存设置 | 1. 切换主题 2. 点击"保存配置" 3. 刷新页面 |
设置保持不变 |
| 重置设置 | 1. 修改多个设置 2. 点击"重置配置" |
恢复为默认值（浅色模式） |
5.2 浏览器兼容性
测试浏览器：
- ✅ Chrome (最新版)
- ✅ Firefox (最新版)
- ✅ Edge (最新版)
- ✅ Safari (最新版)
6. 部署方案
6.1 部署步骤
-
修改代码
# 修改 ruoyi-ui/src/settings.js -
提交代码
git add ruoyi-ui/src/settings.js git commit -m "feat: 将默认主题修改为浅色模式" -
构建前端
cd ruoyi-ui npm run build:prod -
部署静态资源
- 将
ruoyi-ui/dist/目录部署到生产服务器
- 将
-
验证部署
- 清除浏览器缓存
- 访问系统
- 验证新用户看到浅色模式
6.2 回滚方案
如果发现问题，可快速回滚：
// 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- 主题颜色选择器