1
0

feat: 实现多主题系统,支持6套主题切换和设置页面

重构 ThemeContext 为多主题模型(themeId + followSystem + systemIsDark),
新增设置页面(主题下拉栏 + 跟随系统开关),移除旧 ThemeToggle 按钮,
引入 antd-style 和 clsx 依赖支持 MUI/shadcn/Bootstrap/玻璃主题。
This commit is contained in:
2026-04-17 00:06:08 +08:00
parent c5b3d9dfc7
commit ddd284c1ca
21 changed files with 1609 additions and 153 deletions

View File

@@ -0,0 +1,151 @@
# 主题系统
## Purpose
提供多主题选择功能,支持 6 套主题切换、跟随系统暗色模式、主题注册表管理和设置页面。
## Requirements
### Requirement: 提供多主题选择功能
前端 SHALL 提供 6 套主题供用户选择默认、暗黑、MUI、shadcn、Bootstrap、玻璃。
#### Scenario: 默认主题
- **WHEN** 用户首次访问应用且无持久化偏好
- **THEN** 前端 SHALL 使用"默认"主题
- **THEN** ConfigProvider SHALL 应用 `theme.defaultAlgorithm`
#### Scenario: 切换到暗黑主题
- **WHEN** 用户在设置页面选择"暗黑"主题
- **THEN** 前端 SHALL 应用"暗黑"主题
- **THEN** ConfigProvider SHALL 应用 `theme.darkAlgorithm`
#### Scenario: 切换到 MUI 主题
- **WHEN** 用户在设置页面选择"MUI"主题
- **THEN** 前端 SHALL 应用 MUI 主题的完整配置algorithm + token + 组件样式)
#### Scenario: 切换到 shadcn 主题
- **WHEN** 用户在设置页面选择"shadcn"主题
- **THEN** 前端 SHALL 应用 shadcn 主题的完整配置
#### Scenario: 切换到 Bootstrap 主题
- **WHEN** 用户在设置页面选择"Bootstrap"主题
- **THEN** 前端 SHALL 应用 Bootstrap 主题的完整配置
#### Scenario: 切换到玻璃主题
- **WHEN** 用户在设置页面选择"玻璃"主题
- **THEN** 前端 SHALL 应用玻璃主题的完整配置
### Requirement: 提供跟随系统功能
前端 SHALL 提供跟随系统开关,开启后自动检测 OS 暗色模式状态。
#### Scenario: 开启跟随系统且 OS 处于暗色模式
- **WHEN** 用户开启"跟随系统"开关
- **AND** OS 当前处于暗色模式
- **THEN** 前端 SHALL 强制使用"暗黑"主题
- **AND** 忽略用户在下拉栏选择的主题
#### Scenario: 开启跟随系统且 OS 处于亮色模式
- **WHEN** 用户开启"跟随系统"开关
- **AND** OS 当前处于亮色模式
- **THEN** 前端 SHALL 使用用户在下拉栏选择的主题
#### Scenario: 关闭跟随系统
- **WHEN** 用户关闭"跟随系统"开关
- **THEN** 前端 SHALL 始终使用用户在下拉栏选择的主题
- **AND** 忽略 OS 暗色模式状态
#### Scenario: OS 暗色模式实时变化
- **WHEN** "跟随系统"开关处于开启状态
- **AND** OS 从亮色模式切换到暗色模式
- **THEN** 前端 SHALL 自动切换到"暗黑"主题
- **WHEN** OS 从暗色模式切换到亮色模式
- **THEN** 前端 SHALL 自动恢复为用户选择的主题
### Requirement: 持久化主题偏好
前端 SHALL 使用 localStorage 持久化用户的主题偏好。
#### Scenario: 保存主题选择
- **WHEN** 用户选择主题
- **THEN** 前端 SHALL 将主题 ID 保存到 localStorage 键 `nex-theme-id`
- **THEN** 值 SHALL 为有效的主题标识符(`default``dark``mui``shadcn``bootstrap``glass`
#### Scenario: 保存跟随系统偏好
- **WHEN** 用户切换跟随系统开关
- **THEN** 前端 SHALL 将偏好保存到 localStorage 键 `nex-follow-system`
- **THEN** 值 SHALL 为 `'true'``'false'`
#### Scenario: 恢复偏好
- **WHEN** 用户重新访问应用
- **THEN** 前端 SHALL 从 localStorage 读取 `nex-theme-id``nex-follow-system`
- **THEN** 如果 `nex-theme-id` 无效或不存在SHALL 使用 `'default'`
- **THEN** 如果 `nex-follow-system` 不存在SHALL 使用 `false`
#### Scenario: 忽略旧键名
- **WHEN** localStorage 中存在旧键 `theme-mode`
- **THEN** 前端 SHALL 忽略该值
- **THEN** 前端 SHALL NOT 读取或迁移该键
### Requirement: 提供设置页面
前端 SHALL 提供设置页面,使用卡片布局组织设置内容。
#### Scenario: 主题卡片
- **WHEN** 用户访问设置页面
- **THEN** 前端 SHALL 显示主题设置卡片
- **THEN** 卡片内 SHALL 包含主题下拉栏和跟随系统开关
#### Scenario: 主题下拉栏
- **WHEN** 用户展开主题下拉栏
- **THEN** 下拉栏 SHALL 列出所有 6 套主题默认、暗黑、MUI、shadcn、Bootstrap、玻璃
- **THEN** 当前选中的主题 SHALL 被高亮显示
- **WHEN** 用户选择一个主题
- **THEN** 前端 SHALL 立即切换到该主题
#### Scenario: 跟随系统开关
- **WHEN** 用户切换跟随系统开关
- **THEN** 前端 SHALL 立即应用新的跟随系统设置
- **THEN** 开关状态 SHALL 反映当前设置
#### Scenario: 侧边栏设置入口
- **WHEN** 渲染侧边栏菜单
- **THEN** 菜单 SHALL 包含"设置"菜单项
- **THEN** 菜单项 SHALL 使用 `SettingOutlined` 图标
- **WHEN** 用户点击"设置"菜单项
- **THEN** 前端 SHALL 导航到 `/settings` 路由
### Requirement: 使用主题注册表管理主题
前端 SHALL 使用主题注册表统一管理所有主题配置。
#### Scenario: 主题注册表结构
- **WHEN** 应用初始化
- **THEN** 主题注册表 SHALL 包含 6 套主题的完整配置
- **THEN** 每套主题 SHALL 通过 `useConfig()` hook 返回 `ConfigProviderProps`
#### Scenario: 主题文件组织
- **THEN** 主题文件 SHALL 位于 `src/themes/` 目录
- **THEN** 每套主题 SHALL 有独立的配置文件
- **THEN** `src/themes/index.ts` SHALL 导出注册表和类型定义