lanyuanxiaoyao
ddd284c1ca
重构 ThemeContext 为多主题模型（themeId + followSystem + systemIsDark）， 新增设置页面（主题下拉栏 + 跟随系统开关），移除旧 ThemeToggle 按钮， 引入 antd-style 和 clsx 依赖支持 MUI/shadcn/Bootstrap/玻璃主题。
78 lines
2.9 KiB
Markdown
78 lines
2.9 KiB
Markdown
# 主题切换
|
||
|
||
## Purpose
|
||
|
||
管理主题状态与应用，使用 React Context 提供全局主题配置，支持多主题切换和持久化。
|
||
|
||
## Requirements
|
||
|
||
### Requirement: 持久化主题偏好
|
||
|
||
前端 SHALL 使用 localStorage 持久化用户的主题偏好。
|
||
|
||
#### Scenario: 保存主题偏好
|
||
|
||
- **WHEN** 用户选择主题或切换跟随系统开关
|
||
- **THEN** 前端 SHALL 将主题 ID 保存到 localStorage 键 `nex-theme-id`
|
||
- **THEN** 前端 SHALL 将跟随系统偏好保存到 localStorage 键 `nex-follow-system`
|
||
|
||
#### Scenario: 恢复主题偏好
|
||
|
||
- **WHEN** 用户重新访问前端应用
|
||
- **THEN** 前端 SHALL 从 localStorage 读取 `nex-theme-id`
|
||
- **THEN** 前端 SHALL 从 localStorage 读取 `nex-follow-system`
|
||
- **THEN** 如果 `nex-theme-id` 不存在或无效，SHALL 使用 `'default'`
|
||
- **THEN** 如果 `nex-follow-system` 不存在，SHALL 使用 `false`
|
||
|
||
#### Scenario: 刷新页面保持设置
|
||
|
||
- **WHEN** 用户在任意主题和跟随系统设置下刷新浏览器
|
||
- **THEN** 前端 SHALL 保持用户的选择
|
||
|
||
### Requirement: 使用 React Context 管理主题状态
|
||
|
||
前端 SHALL 使用 React Context 提供全局主题状态。
|
||
|
||
#### Scenario: 主题 Context 提供
|
||
|
||
- **WHEN** 应用初始化
|
||
- **THEN** ThemeContext SHALL 提供 `themeId`（当前选择的主题 ID）
|
||
- **THEN** ThemeContext SHALL 提供 `followSystem`（跟随系统开关状态）
|
||
- **THEN** ThemeContext SHALL 提供 `systemIsDark`（OS 暗色模式状态）
|
||
- **THEN** ThemeContext SHALL 提供 `effectiveThemeId`（计算后的实际主题 ID）
|
||
- **THEN** ThemeContext SHALL 提供 `setThemeId`（设置主题方法）
|
||
- **THEN** ThemeContext SHALL 提供 `setFollowSystem`（设置跟随系统方法）
|
||
|
||
#### Scenario: 主题 Context 使用
|
||
|
||
- **WHEN** 组件需要访问或修改主题
|
||
- **THEN** 组件 SHALL 使用 `useTheme` hook
|
||
- **THEN** `useTheme` SHALL 返回当前主题状态和操作方法
|
||
- **THEN** 在 ThemeProvider 外使用 `useTheme` SHALL 抛出错误
|
||
|
||
#### Scenario: 计算有效主题
|
||
|
||
- **WHEN** `followSystem` 为 `true` 且 `systemIsDark` 为 `true`
|
||
- **THEN** `effectiveThemeId` SHALL 为 `'dark'`
|
||
- **WHEN** `followSystem` 为 `true` 且 `systemIsDark` 为 `false`
|
||
- **THEN** `effectiveThemeId` SHALL 为 `themeId`
|
||
- **WHEN** `followSystem` 为 `false`
|
||
- **THEN** `effectiveThemeId` SHALL 为 `themeId`
|
||
|
||
### Requirement: 集成 Ant Design ConfigProvider
|
||
|
||
前端 SHALL 使用 ConfigProvider 应用主题到 Ant Design 组件。
|
||
|
||
#### Scenario: ConfigProvider 主题配置
|
||
|
||
- **WHEN** 渲染应用
|
||
- **THEN** 前端 SHALL 使用 ConfigProvider 包裹应用
|
||
- **THEN** ConfigProvider 的 theme 属性 SHALL 由当前 `effectiveThemeId` 对应的主题配置决定
|
||
- **THEN** 配置 SHALL 包含完整的 `algorithm`、`token` 和组件样式覆盖
|
||
|
||
#### Scenario: 组件自动应用主题
|
||
|
||
- **WHEN** 主题切换
|
||
- **THEN** 所有 Ant Design 组件 SHALL 自动应用新主题
|
||
- **THEN** 主题切换 SHALL 平滑过渡，无闪烁
|