1
0

feat: 升级 Ant Design 6 并实现主题切换功能

- 升级 antd 从 5.24.9 到 6.3.5,@ant-design/icons 从 5.6.1 到 6.1.1
- 新增 ThemeContext 和 ThemeToggle 组件,支持明暗主题切换
- 移除自定义 SCSS 样式,采用 Ant Design 主题系统
- 测试环境从 jsdom 切换到 happy-dom,提升测试性能
- 更新 AppLayout、ModelForm、ProviderForm 以适配新主题系统
This commit is contained in:
2026-04-16 13:31:30 +08:00
parent 1580b5b838
commit 47ecbadc7c
15 changed files with 374 additions and 176 deletions

View File

@@ -133,37 +133,45 @@ TBD - 提供供应商、模型配置和用量统计的前端管理界面
### Requirement: 使用无组件库的最小 UI
前端 SHALL 使用 Ant Design 5 作为 UI 组件库。
前端 SHALL 使用 Ant Design 6 作为 UI 组件库。
#### Scenario: Ant Design 组件使用
- **WHEN** 实现前端
- **THEN** 它 SHALL 使用 Ant Design 5 组件Table、Form、Modal、Menu、Tag、Popconfirm、DatePicker、Button、Select 等)
- **THEN** 它 SHALL 使用 Ant Design 6 组件Table、Form、Modal、Menu、Tag、Popconfirm、DatePicker、Button、Select 等)
- **THEN** 它 SHALL 使用 @ant-design/icons 提供图标
- **THEN** 图标 SHALL 优先使用图标库中已有的图标
#### Scenario: Ant Design 默认主题
#### Scenario: Ant Design 主题支持
- **WHEN** 配置 Ant Design 主题
- **THEN** 前端 SHALL 使用 Ant Design 默认主题,不进行自定义主题色配置
- **THEN** 前端 SHALL NOT 支持暗色模式切换
- **THEN** 前端 SHALL 支持亮色和暗色模式切换
- **THEN** 前端 SHALL 使用 Ant Design v6 的 theme.darkAlgorithm 和 theme.defaultAlgorithm
- **THEN** 前端 SHALL 通过 ConfigProvider 动态切换主题
### Requirement: SCSS 样式
### Requirement: 样式体系
前端样式 SHALL 全部使用 SCSS禁止使用纯 CSS 文件
前端样式 SHALL 优先使用 Ant Design 样式体系SCSS 作为补充工具
#### Scenario: 样式文件规范
#### Scenario: Ant Design 样式优先
- **WHEN** 编写样式
- **THEN** 前端 SHALL 使用 SCSS*.scss 文件)
- **WHEN** 实现组件样式
- **THEN** 前端 SHALL 优先使用 Ant Design 组件的 style prop
- **THEN** 前端 SHALL 优先使用 Ant Design v6 的语义化样式classNames 和 styles props
- **THEN** 前端 SHALL 使用 Ant Design Layout 组件处理布局
#### Scenario: SCSS 补充使用
- **WHEN** Ant Design 样式体系无法满足需求
- **THEN** 前端 MAY 使用 SCSS 作为补充
- **THEN** SCSS 文件 SHALL 使用 *.module.scssSCSS Modules
- **THEN** 前端 SHALL NOT 使用纯 CSS 文件(*.css
- **THEN** 前端 SHALL NOT 使用 CSS-in-JS 方案
#### Scenario: SCSS Modules 使用
#### Scenario: 移除冗余 SCSS
- **WHEN** 编写组件级样式
- **THEN** 前端 SHALL 使用 SCSS Modules*.module.scss
- **THEN** 全局样式仅保留 index.scss 做 reset 和 CSS variables
- **WHEN** SCSS 文件仅实现 Ant Design 已有的功能
- **THEN** 前端 SHALL 移除该 SCSS 文件
- **THEN** 前端 SHALL 使用 Ant Design 内置功能替代
### Requirement: 提供导航

View File

@@ -0,0 +1,111 @@
# 主题切换
## Purpose
提供亮色/暗色模式切换功能,允许用户自定义界面主题并持久化偏好。
## Requirements
### Requirement: 提供主题切换功能
前端 SHALL 提供亮色/暗色模式切换功能,允许用户自定义界面主题。
#### Scenario: 初始加载默认主题
- **WHEN** 用户首次访问前端应用
- **THEN** 前端 SHALL 使用亮色模式作为默认主题
- **THEN** 前端 SHALL 应用 Ant Design defaultAlgorithm
#### Scenario: 切换到暗色模式
- **WHEN** 用户点击主题切换按钮(当前为亮色模式)
- **THEN** 前端 SHALL 切换到暗色模式
- **THEN** 前端 SHALL 应用 Ant Design darkAlgorithm
- **THEN** 所有 Ant Design 组件 SHALL 自动应用暗色主题
- **THEN** 主题切换按钮图标 SHALL 从月亮图标变为太阳图标
#### Scenario: 切换到亮色模式
- **WHEN** 用户点击主题切换按钮(当前为暗色模式)
- **THEN** 前端 SHALL 切换到亮色模式
- **THEN** 前端 SHALL 应用 Ant Design defaultAlgorithm
- **THEN** 所有 Ant Design 组件 SHALL 自动应用亮色主题
- **THEN** 主题切换按钮图标 SHALL 从太阳图标变为月亮图标
### Requirement: 持久化主题偏好
前端 SHALL 使用 localStorage 持久化用户的主题偏好。
#### Scenario: 保存主题偏好
- **WHEN** 用户切换主题
- **THEN** 前端 SHALL 将主题模式保存到 localStorage
- **THEN** localStorage 键名 SHALL 为 'theme-mode'
- **THEN** 值 SHALL 为 'light' 或 'dark'
#### Scenario: 恢复主题偏好
- **WHEN** 用户重新访问前端应用
- **THEN** 前端 SHALL 从 localStorage 读取 'theme-mode'
- **THEN** 如果存在有效值,前端 SHALL 应用保存的主题
- **THEN** 如果不存在或值无效,前端 SHALL 使用默认亮色模式
#### Scenario: 刷新页面保持主题
- **WHEN** 用户在暗色模式下刷新浏览器
- **THEN** 前端 SHALL 保持暗色模式
- **WHEN** 用户在亮色模式下刷新浏览器
- **THEN** 前端 SHALL 保持亮色模式
### Requirement: 提供主题切换 UI
前端 SHALL 在布局 Header 中提供主题切换按钮。
#### Scenario: 显示主题切换按钮
- **WHEN** 渲染 AppLayout Header
- **THEN** 前端 SHALL 在 Header 右侧显示主题切换按钮
- **THEN** 按钮 SHALL 使用 Ant Design Button 组件type="text"
- **THEN** 按钮图标 SHALL 根据当前主题显示(亮色模式显示月亮图标,暗色模式显示太阳图标)
#### Scenario: 主题切换按钮交互
- **WHEN** 用户点击主题切换按钮
- **THEN** 前端 SHALL 切换主题模式
- **THEN** 按钮 SHALL 显示 Tooltip 提示("切换到暗色模式"或"切换到亮色模式"
### Requirement: 使用 React Context 管理主题状态
前端 SHALL 使用 React Context 提供全局主题状态。
#### Scenario: 主题 Context 提供
- **WHEN** 应用初始化
- **THEN** 前端 SHALL 创建 ThemeContext
- **THEN** ThemeContext SHALL 提供 mode当前主题模式
- **THEN** ThemeContext SHALL 提供 toggleTheme切换主题方法
- **THEN** ThemeContext SHALL 提供 setTheme设置主题方法
#### Scenario: 主题 Context 使用
- **WHEN** 组件需要访问或修改主题
- **THEN** 组件 SHALL 使用 useTheme hook
- **THEN** useTheme SHALL 返回当前主题状态和操作方法
- **THEN** 在 ThemeProvider 外使用 useTheme SHALL 抛出错误
### Requirement: 集成 Ant Design ConfigProvider
前端 SHALL 使用 ConfigProvider 应用主题到 Ant Design 组件。
#### Scenario: ConfigProvider 主题配置
- **WHEN** 渲染应用
- **THEN** 前端 SHALL 使用 ConfigProvider 包裹应用
- **THEN** ConfigProvider theme.algorithm SHALL 根据当前主题设置defaultAlgorithm 或 darkAlgorithm
#### Scenario: 组件自动应用主题
- **WHEN** 主题切换
- **THEN** 所有 Ant Design 组件 SHALL 自动应用新主题
- **THEN** 组件 SHALL 无需手动样式调整
- **THEN** 主题切换 SHALL 平滑过渡,无闪烁