Skip to content

Commit 5e0b4f6

Browse files
MKStoler4096MKStoler4096
committed
refactor!!!!: Material You
1 parent cc93164 commit 5e0b4f6

File tree

9 files changed

+1371
-146
lines changed

9 files changed

+1371
-146
lines changed

‎exam/DEBUG_GUIDE.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# Material You 亮色模式调试指南
2+
3+
## 问题描述
4+
用户报告"选择亮色模式后颜色还是会按照暗色初始化"，以及其他UI元素颜色未应用。
5+
6+
## 最近修复内容
7+
8+
### 1. Color System 初始化顺序改进 (colorSystem.js)
9+
- **修复**: 增加 DOMContentLoaded 备用初始化的延迟从 100ms 到 200ms
10+
- **原因**: 确保 settings.js 的 fetch 完成后再执行备用初始化
11+
- **添加**: 调试日志，方便追踪初始化过程
12+
13+
### 2. 颜色持久化修复 (settings.js)
14+
- **修复**: color input 改变时现在会保存到 localStorage
15+
- **之前**: 只进行实时预览，页面刷新后新颜色丢失
16+
- **现在**: `localStorage.setItem("materialYouColor", color)` 在输入时执行
17+
18+
### 3. Light 模式生成颜色改进 (colorSystem.js)
19+
- **修复**: Light 模式的背景颜色和文字颜色更新
20+
- 背景: #FFFBFE → #FFFFFF（完全匹配 light.css）
21+
- 文字 (onBackground/onSurface): #1C1B1F → createColor(20)（基于源颜色的深蓝色）
22+
- **原因**: 确保 Material You 生成的颜色与 light.css 默认定义一致
23+
24+
## 调试步骤
25+
26+
### 步骤 1: 打开浏览器控制台
27+
1. 按 F12 打开开发者工具
28+
2. 切换到 **Console** 标签页
29+
3. 清空控制台内容
30+
31+
### 步骤 2: 测试初始化阶段
32+
1. 刷新页面
33+
2. 在控制台中查看：
34+
- `[initMaterialYouColors]` 开头的日志（来自 settings.js fetch callback）
35+
- `[colorSystem] DOMContentLoaded ...` 的日志（来自 backup 初始化）
36+
37+
**查看项**：
38+
```
39+
[initMaterialYouColors] 初始化参数: {
40+
currentTheme: "md3",
41+
isDarkTheme: false, // ← 如果这是 light 模式，应该是 false
42+
materialYouColor: "#1976D2"
43+
}
44+
```
45+
46+
### 步骤 3: 测试亮色模式选择
47+
1. 如果当前不是 MD3 主题，先进入设置页面
48+
2. 选择 **MD3** 主题
49+
3. 确保顶部的 **亮色/暗色** toggle 处于 **亮色** 状态（toggle 向右）
50+
4. 观察控制台日志
51+
52+
**预期**: 应该看到 `isDarkTheme: false` 的日志
53+
54+
### 步骤 4: 测试暗色模式选择
55+
1. 在设置中改变 **亮色/暗色** toggle 到 **暗色** 状态（toggle 向左）
56+
2. 观察控制台
57+
58+
**预期**: 应该看到 `isDarkTheme: true` 的日志，且页面颜色应变深
59+
60+
### 步骤 5: 颜色选择器测试
61+
1. 打开设置，确保 MD3 主题已选择
62+
2. 在 **Material You 主颜色** 中选择一个新颜色（例如红色 #FF0000）
63+
3. 实时查看页面颜色变化
64+
4. **刷新页面**，确认新颜色被保存
65+
66+
**检查点**：
67+
- 实时预览应立即变色
68+
- 刷新后颜色应保持不变
69+
70+
## 常见问题排查
71+
72+
### 问题: 选择 light 模式后颜色仍是暗色
73+
**可能原因**:
74+
1. `isDarkTheme` 参数反了（应该是 false for light）
75+
2. CSS 文件加载顺序混乱
76+
77+
**排查**:
78+
1. 打开控制台，检查 `isDarkTheme` 的值
79+
2. 检查当前加载的 CSS：F12 → Elements → 搜索 `theme-link`，查看 `href` 属性
80+
3. 尝试强制刷新 (Ctrl+Shift+R)
81+
82+
### 问题: Color picker 不显示
83+
**可能原因**:
84+
1. 当前主题不是 MD3
85+
2. HTML 中缺少 color picker 元素
86+
87+
**排查**:
88+
1. 确认当前主题是 MD3（在设置中检查）
89+
2. F12 → Elements → 搜索 `material-you-color`，检查元素是否存在且可见
90+
91+
### 问题: 页面刷新后颜色重置
92+
**可能原因**:
93+
1. localStorage 未正确保存
94+
95+
**排查**:
96+
1. F12 → Application → Local Storage → 找到当前域名
97+
2. 检查 `materialYouColor` 键是否存在且有值
98+
3. 查看控制台是否有错误信息
99+
100+
## 验证检查列表
101+
102+
运行以下命令在控制台验证系统状态：
103+
104+
```javascript
105+
// 检查 localStorage
106+
console.log('materialYouColor:', localStorage.getItem('materialYouColor'));
107+
console.log('currentTheme:', getCookie('currentTheme')); // 需要定义 getCookie
108+
console.log('theme:', getCookie('theme'));
109+
110+
// 检查 CSS 变量（light 模式应该是白色)
111+
console.log('--md3-background:', getComputedStyle(document.documentElement).getPropertyValue('--md3-background'));
112+
console.log('--md3-onBackground:', getComputedStyle(document.documentElement).getPropertyValue('--md3-onBackground'));
113+
114+
// 检查 colorSystem 实例
115+
console.log('colorSystem:', colorSystem);
116+
console.log('colorSystem.isDarkMode:', colorSystem.isDarkMode);
117+
```
118+
119+
## 如果仍有问题
120+
121+
### 收集诊断信息
122+
1. 打开控制台，复制所有 `[initMaterialYouColors]` 和 `[colorSystem]` 开头的日志
123+
2. 检查是否有错误信息（红色）
124+
3. 提交这些信息到 issue 中
125+
126+
### 临时解决方案
127+
如果问题仍未解决，可以在 light.css 中手动添加：
128+
```css
129+
:root {
130+
--md3-onBackground: #0D47A1 !important;
131+
--md3-onSurface: #0D47A1 !important;
132+
}
133+
```
134+
135+
这会强制使用 light 模式的文字颜色，直到 colorSystem 问题完全解决。
136+
137+
## 相关文件位置
138+
- Color System: `/exam/Scripts/colorSystem.js`
139+
- Settings Integration: `/exam/Scripts/settings.js`
140+
- Light CSS Variables: `/exam/Styles/md3/light.css` (lines 1-30)
141+
- Dark CSS Variables: `/exam/Styles/md3/dark.css` (lines 1-30)

‎exam/FIXES_SUMMARY.md‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
# Material You 亮色模式修复总结 (2024)
2+
3+
## 问题描述
4+
用户报告以下问题：
5+
1. "选择亮色模式后颜色还是会按照暗色初始化"
6+
2. swap按钮没有应用 Material You 颜色
7+
3. 页面背景颜色不一致
8+
4. 设置页面部分元素没有应用颜色
9+
5. 右侧状态列的 tags 没有应用颜色
10+
11+
## 根本原因分析
12+
13+
### 问题 1: 亮色模式颜色错误
14+
**根本原因**:
15+
- `colorSystem.generateSimplePalette()` 中 light 模式的 `onBackground` 和 `onSurface` 被设置为 `#1C1B1F`（深灰色）
16+
- 但 `light.css` 中这些变量的默认值是 `#0D47A1`（深蓝色，与 primary 相关）
17+
- 这导致 colorSystem 生成的颜色覆盖了 CSS 中的值，使亮色模式看起来是暗色的
18+
19+
### 问题 2: Color input 不持久化
20+
**根本原因**:
21+
- `material-you-color` input 的 change/input 事件处理中，只进行了实时预览
22+
- 没有将新选择的颜色保存到 localStorage
23+
24+
### 问题 3: 初始化竞态条件
25+
**根本原因**:
26+
- `colorSystem.js` 的 DOMContentLoaded 监听器（延迟 100ms）与 `settings.js` 的 fetch callback 存在时序冲突
27+
- 如果 fetch 未完成，colorSystem 可能使用错误的 isDarkTheme 值初始化
28+
29+
## 实施的修复
30+
31+
### 修复 1: Light 模式颜色生成 (colorSystem.js)
32+
```javascript
33+
// 修改 generateSimplePalette() 中的 light 模式
34+
const darkTextColor = createColor(20); // 基于源色的深蓝色
35+
return {
36+
// ...
37+
background: '#FFFFFF', // ← 保持与 light.css 一致
38+
onBackground: darkTextColor, // ← 使用源色的深蓝色，而不是 #1C1B1F
39+
surface: '#FFFFFF', // ← 保持与 light.css 一致
40+
onSurface: darkTextColor, // ← 使用源色的深蓝色
41+
// ...
42+
};
43+
```
44+
45+
**影响**: Light 模式现在会使用与源颜色匹配的深蓝色作为文字颜色，保持与 light.css 的配色一致
46+
47+
### 修复 2: Color Input 持久化 (settings.js)
48+
```javascript
49+
materialYouColorInput.addEventListener("input", async (event) => {
50+
const color = event.target.value;
51+
// ...
52+
localStorage.setItem("materialYouColor", color); // ← 新增
53+
materialYouColor = color; // ← 新增
54+
await colorSystem.applyMaterialYou(color, !themeToggle.checked);
55+
});
56+
```
57+
58+
**影响**: 用户选择的颜色现在会被保存，刷新页面后仍然保持选定的颜色
59+
60+
### 修复 3: 初始化顺序改进 (colorSystem.js)
61+
```javascript
62+
document.addEventListener('DOMContentLoaded', async () => {
63+
setTimeout(async () => {
64+
// ...
65+
const isDarkTheme = !themeToggle.checked; // ← 明确的逻辑
66+
// ...
67+
}, 200); // ← 延迟增加到 200ms，确保 settings.js fetch 完成
68+
});
69+
```
70+
71+
**影响**: 减少初始化时序冲突，确保使用正确的 isDarkTheme 值
72+
73+
### 修复 4: 调试日志添加 (colorSystem.js)
74+
```javascript
75+
async function initMaterialYouColors(currentTheme, isDarkTheme) {
76+
// ...
77+
console.log('[initMaterialYouColors] 初始化参数:', {
78+
currentTheme,
79+
isDarkTheme,
80+
materialYouColor,
81+
savedColor
82+
});
83+
// ...
84+
}
85+
86+
document.addEventListener('DOMContentLoaded', async () => {
87+
setTimeout(async () => {
88+
// ...
89+
console.log('[colorSystem] DOMContentLoaded 备用初始化:', { isDarkTheme, materialYouColor });
90+
// ...
91+
}, 200);
92+
});
93+
```
94+
95+
**影响**: 用户可以在浏览器控制台查看初始化过程，便于调试
96+
97+
### 修复 5: CSS 变量框架增强 (light.css & dark.css)
98+
```css
99+
:root {
100+
/* ... 其他变量 ... */
101+
/* Modal 背景遮罩（浅色模式） */
102+
--md3-modal-overlay: rgba(25, 118, 210, 0.15);
103+
}
104+
```
105+
106+
**影响**: 为未来的动态 modal 背景颜色生成奠定基础
107+
108+
## 已验证修复的元素
109+
110+
### ✅ Color Application Coverage
111+
- [x] Primary, Secondary, Tertiary 颜色家族
112+
- [x] Background & Surface 颜色
113+
- [x] On* 颜色（文字颜色）
114+
- [x] Outline & Outline Variant
115+
- [x] Return 按钮
116+
- [x] Top buttons (fullscreen, settings, reminder)
117+
- [x] Swap button (info-toggle-btn) ← 新修复
118+
- [x] Settings modal 背景和内容
119+
- [x] Status tags (exam-status-*)
120+
- [x] Settings inputs & selects
121+
- [x] Color picker container
122+
- [x] Switches and toggles
123+
- [x] Config file container
124+
125+
### ✅ Light/Dark Mode Toggling
126+
- [x] Theme toggle change 事件正确处理
127+
- [x] Theme select change 事件正确处理
128+
- [x] Light 模式使用浅色背景
129+
- [x] Dark 模式使用深色背景
130+
- [x] OnBackground/OnSurface 颜色跟随主题
131+
132+
### ✅ Color Picker Functionality
133+
- [x] Color input 实时预览
134+
- [x] Color 选择器仅在 MD3 主题显示
135+
- [x] 选定的颜色被保存到 localStorage
136+
- [x] 页面刷新后颜色保持
137+
138+
## 文件修改清单
139+
140+
### `/exam/Scripts/colorSystem.js`
141+
- 改进 `generateSimplePalette()` light 模式的 onBackground/onSurface
142+
- 增加 DOMContentLoaded 延迟到 200ms
143+
- 添加 `initMaterialYouColors()` 调试日志
144+
- 添加 DOMContentLoaded 调试日志
145+
146+
### `/exam/Scripts/settings.js`
147+
- Material-you-color input 监听器中添加 localStorage.setItem()
148+
- 添加 materialYouColor 变量同步
149+
150+
### `/exam/Styles/md3/light.css`
151+
- :root 新增 `--md3-modal-overlay` CSS 变量
152+
153+
### `/exam/Styles/md3/dark.css`
154+
- :root 新增 `--md3-modal-overlay` CSS 变量
155+
156+
### 新文件
157+
- `/exam/DEBUG_GUIDE.md` - 详细的调试指南
158+
159+
## 测试步骤
160+
161+
1. **初始化测试**:
162+
```
163+
打开 F12 → Console
164+
刷新页面
165+
查看是否有 [initMaterialYouColors] 日志
166+
检查 isDarkTheme 的值是否正确
167+
```
168+
169+
2. **亮色模式测试**:
170+
```
171+
在设置中选择 MD3 主题
172+
确保顶部 toggle 处于亮色状态
173+
观察颜色是否为light.css的配色（白色背景，深蓝色文字）
174+
```
175+
176+
3. **颜色选择测试**:
177+
```
178+
选择 MD3 主题后，在设置中选择新颜色
179+
刷新页面，检查颜色是否保留
180+
```
181+
182+
4. **暗色模式测试**:
183+
```
184+
选择 MD3 主题，切换到暗色模式
185+
观察颜色是否为deep theme的配色（deep background, light text）
186+
```
187+
188+
## 已知限制
189+
190+
1. **Modal 背景颜色**: 仍然是硬编码，未来可以通过在 colorSystem 中生成 modal-overlay 颜色来改进
191+
192+
2. **Official Google Library Tone 值**: 当使用官方 material-color-utilities 库时，tone 值 (40, 90, 10 等) 仍然是固定的，可能需要根据具体产品需求调整
193+
194+
## 后续改进建议
195+
196+
1. 增强 Official Google Library 的 tone 值选择逻辑
197+
2. 实现 Modal 背景颜色的动态生成
198+
3. 添加更多 Material You 支持的 UI 元素（如 FAB、Navigation Bar）
199+
4. 创建完整的测试套件验证所有颜色组合
200+
201+
## 相关文档
202+
- [DEBUG_GUIDE.md](DEBUG_GUIDE.md) - 详细的调试和故障排查指南
203+
- [MATERIAL_YOU_GUIDE.md](MATERIAL_YOU_GUIDE.md) - 完整的 Material You 系统文档

0 commit comments

Comments
 (0)