186 lines
5.0 KiB
Markdown
186 lines
5.0 KiB
Markdown
# 诗词答题页面主题色支持与代码重构设计文档
|
||
|
||
**日期：** 2026-04-03
|
||
**状态：** 待实现
|
||
**作者：** AI Assistant
|
||
|
||
## 1. 概述
|
||
|
||
### 1.1 目标
|
||
|
||
将诗词答题相关页面重构以支持动态主题色，并将代码分流到 `poetry-page.dart`，实现 UI 和逻辑的分离。
|
||
|
||
### 1.2 范围
|
||
|
||
涉及文件：
|
||
- `lib/views/profile/level/poetry.dart` - 主页面（状态管理、网络请求）
|
||
- `lib/views/profile/level/poetry-page.dart` - UI 组件（选项、标签、布局）
|
||
- `lib/views/profile/level/flow-anim.dart` - 流动边框动画
|
||
- `lib/views/profile/level/distinguish.dart` - 答题记录页面
|
||
- `lib/views/profile/level/level-jilu.dart` - 业务逻辑管理器（无需修改）
|
||
|
||
## 2. 架构设计
|
||
|
||
### 2.1 文件结构
|
||
|
||
```
|
||
lib/views/profile/level/
|
||
├── poetry.dart # 主页面（状态管理、网络请求）
|
||
├── poetry-page.dart # UI 组件（选项、标签、布局）
|
||
├── level-jilu.dart # 业务逻辑管理器
|
||
├── flow-anim.dart # 流动边框动画
|
||
└── distinguish.dart # 答题记录页面
|
||
```
|
||
|
||
### 2.2 职责划分
|
||
|
||
**poetry.dart 职责：**
|
||
- `PoetryLevelPage` 类（StatefulWidget）
|
||
- `_PoetryLevelPageState` 类
|
||
- 状态变量管理
|
||
- 生命周期方法
|
||
- 业务逻辑方法（网络请求、数据处理）
|
||
- `build` 方法的主框架
|
||
|
||
**poetry-page.dart 职责：**
|
||
- UI 组件定义
|
||
- 主题色支持
|
||
- 深色模式适配
|
||
- 组件复用
|
||
|
||
## 3. 组件设计
|
||
|
||
### 3.1 PoetryOptionItem 组件
|
||
|
||
**功能：** 单个答题选项组件
|
||
|
||
**参数：**
|
||
- `option`: dynamic - 选项数据
|
||
- `isSelected`: bool - 是否被选中
|
||
- `isCorrect`: bool - 是否正确
|
||
- `isWrong`: bool - 是否错误
|
||
- `isSubmitting`: bool - 是否正在提交
|
||
- `showFeedback`: bool - 是否显示反馈
|
||
- `isAnswerCorrect`: bool - 答案是否正确
|
||
- `onTap`: Function(int) - 点击回调
|
||
|
||
**主题色支持：**
|
||
- 使用 `ThemeColors.getThemeColor(themeController.themeColorIndexRx.value)` 获取主题色
|
||
- 正确答案使用 `Colors.green`
|
||
- 错误答案使用 `Colors.red`
|
||
- 背景色根据深色模式动态调整
|
||
|
||
### 3.2 PoetryOptionsLayout 组件
|
||
|
||
**功能：** 选项布局组件（支持 2x2 和 1x4 布局）
|
||
|
||
**参数：**
|
||
- `options`: List<dynamic> - 选项列表
|
||
- `selectedAnswer`: int? - 选中的答案
|
||
- `showFeedback`: bool - 是否显示反馈
|
||
- `isAnswerCorrect`: bool - 答案是否正确
|
||
- `isSubmitting`: bool - 是否正在提交
|
||
- `onTap`: Function(int) - 点击回调
|
||
|
||
**布局逻辑：**
|
||
- 检查所有选项是否都少于等于4个字
|
||
- 如果是且选项数>=4，使用 2x2 布局
|
||
- 否则使用 1x4 布局
|
||
|
||
### 3.3 PoetryTag 组件
|
||
|
||
**功能：** 标签组件（显示题目类型、年级、朝代）
|
||
|
||
**参数：**
|
||
- `label`: String - 标签名称
|
||
- `value`: String - 标签值
|
||
|
||
**主题色支持：**
|
||
- 使用主题色作为背景色和文字颜色
|
||
|
||
## 4. 主题色支持策略
|
||
|
||
### 4.1 颜色替换规则
|
||
|
||
**替换：**
|
||
- `AppConstants.primaryColor` → `ThemeColors.getThemeColor(themeController.themeColorIndexRx.value)`
|
||
|
||
**保留：**
|
||
- 正确答案：`Colors.green` / `AppColors.iosGreen`
|
||
- 错误答案：`Colors.red` / `AppColors.iosRed`
|
||
- 背景色：根据深色模式动态调整
|
||
|
||
### 4.2 深色模式支持
|
||
|
||
**判断方式：**
|
||
- 使用 `themeController.isDarkModeRx.value` 判断深色模式
|
||
|
||
**颜色调整：**
|
||
- 背景色：`isDark ? Color(0xFF1A1A1A) : Colors.white`
|
||
- 文字颜色：`isDark ? Colors.grey[300] : Colors.grey[700]`
|
||
- 边框颜色：`isDark ? Colors.white.withAlpha(20) : Colors.black.withAlpha(10)`
|
||
|
||
## 5. 实现步骤
|
||
|
||
### 5.1 创建 poetry-page.dart
|
||
|
||
1. 创建 `PoetryOptionItem` 组件
|
||
2. 创建 `PoetryOptionsLayout` 组件
|
||
3. 创建 `PoetryTag` 组件
|
||
4. 添加主题色支持
|
||
5. 添加深色模式支持
|
||
|
||
### 5.2 修改 poetry.dart
|
||
|
||
1. 移除 `_buildOptionItem` 方法
|
||
2. 移除 `_buildOptionsLayout` 方法
|
||
3. 移除 `_buildTag` 方法
|
||
4. 导入 `poetry-page.dart`
|
||
5. 使用新组件替换原有方法
|
||
6. 添加主题色支持
|
||
|
||
### 5.3 修改 flow-anim.dart
|
||
|
||
1. 添加主题色支持
|
||
2. 使用 `ThemeColors.getThemeColor()` 替换硬编码颜色
|
||
|
||
### 5.4 修改 distinguish.dart
|
||
|
||
1. 添加主题色支持
|
||
2. 使用 `ThemeColors.getThemeColor()` 替换硬编码颜色
|
||
|
||
## 6. 测试要点
|
||
|
||
### 6.1 功能测试
|
||
|
||
- 选项点击正常
|
||
- 答案提交正常
|
||
- 反馈显示正常
|
||
- 布局切换正常（2x2 和 1x4）
|
||
|
||
### 6.2 主题色测试
|
||
|
||
- 主题色切换正常
|
||
- 所有组件颜色同步更新
|
||
- 深色模式切换正常
|
||
|
||
### 6.3 兼容性测试
|
||
|
||
- 关怀模式正常显示
|
||
- 底部导航栏不遮挡内容
|
||
- 动画效果正常
|
||
|
||
## 7. 注意事项
|
||
|
||
1. **保持布局不变**：重构过程中不修改页面布局
|
||
2. **代码平衡**：确保两个文件代码量相近
|
||
3. **性能优化**：使用 `Obx` 进行响应式更新，避免不必要的重建
|
||
4. **向后兼容**：确保现有功能不受影响
|
||
|
||
## 8. 后续优化
|
||
|
||
1. 考虑将更多组件提取到 `poetry-page.dart`
|
||
2. 添加单元测试
|
||
3. 优化性能，减少不必要的重建
|
||
4. 添加更多主题色选项
|