370 lines
9.4 KiB
Markdown
370 lines
9.4 KiB
Markdown
# 加载动画系统清理与文本效果修复 - 设计文档
|
||
|
||
## 1. 架构概述
|
||
|
||
本次优化分为两个独立模块：
|
||
1. **加载动画清理模块**：移除旧代码，统一使用 `PageLoader`
|
||
2. **文本效果修复模块**：为文本特效添加文章容器选择器支持
|
||
|
||
## 2. 加载动画清理设计
|
||
|
||
### 2.1 问题分析
|
||
|
||
**旧代码位置**：`argontheme.js` 第 4970-5040 行
|
||
|
||
**旧代码特征**：
|
||
- 使用 `article-loading-overlay` ID
|
||
- 手动创建 DOM 元素和骨架屏 HTML
|
||
- 使用 `setInterval` 模拟进度
|
||
- 监听 `window.load` 事件
|
||
- PJAX 事件处理中重复创建相同元素
|
||
|
||
**新系统特征**：
|
||
- 使用 `PageLoader` 模块（IIFE 封装）
|
||
- 统一的 `loading-*` 类名前缀
|
||
- SVG 圆环进度指示器
|
||
- 智能进度算法（缓动函数）
|
||
- 延迟显示和最小显示时间控制
|
||
|
||
### 2.2 清理策略
|
||
|
||
#### 2.2.1 页面初始加载
|
||
**旧代码**（需移除）：
|
||
```javascript
|
||
// 第 4970-4995 行
|
||
var bar = document.getElementById('page-loading-bar');
|
||
// ... 创建 article-loading-overlay ...
|
||
window.addEventListener('load', function() { ... });
|
||
```
|
||
|
||
**新方案**：
|
||
- 在 `DOMContentLoaded` 时调用 `PageLoader.show()`
|
||
- 在 `window.load` 时调用 `PageLoader.hide()`
|
||
- 已在现有代码中实现，无需修改
|
||
|
||
#### 2.2.2 PJAX 加载动画
|
||
**旧代码**（需移除）：
|
||
```javascript
|
||
// 第 4997-5033 行
|
||
function initPjaxAnimations() {
|
||
jQuery(document).on('pjax:start', function() {
|
||
// ... 创建 article-loading-overlay ...
|
||
});
|
||
jQuery(document).on('pjax:end', function() {
|
||
// ... 移除 overlay ...
|
||
});
|
||
}
|
||
```
|
||
|
||
**新方案**：
|
||
- `pjax:start` 时调用 `PageLoader.show()`
|
||
- `pjax:end` 时调用 `PageLoader.hide()`
|
||
- 需要新增此部分代码
|
||
|
||
### 2.3 实现步骤
|
||
|
||
1. **定位旧代码**：确认第 4970-5040 行的完整范围
|
||
2. **移除旧代码**：删除整个旧的加载动画实现
|
||
3. **添加 PJAX 支持**：在 `PageLoader` 模块后添加 PJAX 事件监听
|
||
4. **测试验证**：确保页面加载和 PJAX 导航都正常
|
||
|
||
### 2.4 新增 PJAX 集成代码
|
||
|
||
```javascript
|
||
// PJAX 加载动画集成
|
||
if (typeof jQuery !== 'undefined') {
|
||
jQuery(document).on('pjax:start', function() {
|
||
PageLoader.show();
|
||
});
|
||
|
||
jQuery(document).on('pjax:end', function() {
|
||
PageLoader.hide();
|
||
// 重新初始化页面动画
|
||
setTimeout(function() {
|
||
initImageLoadAnimation();
|
||
initScrollAnimations();
|
||
initSmoothScroll();
|
||
}, 100);
|
||
});
|
||
}
|
||
```
|
||
|
||
## 3. 文本效果修复设计
|
||
|
||
### 3.1 问题分析
|
||
|
||
**当前样式选择器**：
|
||
```css
|
||
.color-curtain { ... }
|
||
.text-blur { ... }
|
||
.huhua { ... }
|
||
```
|
||
|
||
**问题**：
|
||
- 缺少文章容器选择器（`article .entry-content`、`.article-content`）
|
||
- 在某些文章布局中可能不生效
|
||
|
||
### 3.2 修复策略
|
||
|
||
参考黑幕样式的修复方式，为每个文本效果添加文章容器选择器。
|
||
|
||
#### 3.2.1 彩色黑幕（color-curtain）
|
||
|
||
**当前样式**：
|
||
```css
|
||
.color-curtain, .color-curtain a, a .color-curtain, .color-curtain a.new {
|
||
background-color: var(--curtain-bg, #252525) !important;
|
||
color: var(--curtain-bg, #252525) !important;
|
||
/* ... */
|
||
}
|
||
```
|
||
|
||
**修复方案**：
|
||
```css
|
||
/* 基础样式 */
|
||
.color-curtain,
|
||
article .entry-content .color-curtain,
|
||
.article-content .color-curtain {
|
||
background-color: var(--curtain-bg, #252525) !important;
|
||
color: var(--curtain-bg, #252525) !important;
|
||
/* ... */
|
||
}
|
||
|
||
/* 链接样式 */
|
||
.color-curtain a,
|
||
article .entry-content .color-curtain a,
|
||
.article-content .color-curtain a {
|
||
color: inherit !important;
|
||
/* ... */
|
||
}
|
||
|
||
/* 悬停样式 */
|
||
.color-curtain:hover,
|
||
article .entry-content .color-curtain:hover,
|
||
.article-content .color-curtain:hover {
|
||
color: var(--curtain-fg, #fff) !important;
|
||
}
|
||
```
|
||
|
||
**夜间模式优化**：
|
||
```css
|
||
html.darkmode .color-curtain,
|
||
html.darkmode article .entry-content .color-curtain,
|
||
html.darkmode .article-content .color-curtain {
|
||
--curtain-bg: #1a1a1a;
|
||
--curtain-fg: #e0e0e0;
|
||
}
|
||
```
|
||
|
||
#### 3.2.2 模糊文本（text-blur）
|
||
|
||
**当前样式**：
|
||
```css
|
||
.text-blur, .text-blur a, a .text-blur, .text-blur a.new {
|
||
filter: blur(2px) !important;
|
||
/* ... */
|
||
}
|
||
```
|
||
|
||
**修复方案**：
|
||
```css
|
||
.text-blur,
|
||
article .entry-content .text-blur,
|
||
.article-content .text-blur {
|
||
filter: blur(2px) !important;
|
||
transition: filter var(--text-blur-transition-time, .2s) ease;
|
||
display: inline-block;
|
||
}
|
||
|
||
.text-blur:hover,
|
||
article .entry-content .text-blur:hover,
|
||
.article-content .text-blur:hover {
|
||
filter: none !important;
|
||
}
|
||
```
|
||
|
||
#### 3.2.3 划掉文本（huhua）
|
||
|
||
**当前样式**：
|
||
```css
|
||
.huhua {
|
||
color: #9ea3a9 !important;
|
||
text-decoration: line-through !important;
|
||
/* ... */
|
||
}
|
||
```
|
||
|
||
**修复方案**：
|
||
```css
|
||
.huhua,
|
||
article .entry-content .huhua,
|
||
.article-content .huhua {
|
||
color: #9ea3a9 !important;
|
||
text-decoration: line-through !important;
|
||
text-shadow: none !important;
|
||
transition: color .2s ease;
|
||
}
|
||
|
||
.huhua:hover,
|
||
article .entry-content .huhua:hover,
|
||
.article-content .huhua:hover {
|
||
color: #7f858b !important;
|
||
}
|
||
```
|
||
|
||
**夜间模式优化**：
|
||
```css
|
||
html.darkmode .huhua,
|
||
html.darkmode article .entry-content .huhua,
|
||
html.darkmode .article-content .huhua {
|
||
color: #6a7075 !important;
|
||
}
|
||
|
||
html.darkmode .huhua:hover,
|
||
html.darkmode article .entry-content .huhua:hover,
|
||
html.darkmode .article-content .huhua:hover {
|
||
color: #555a5f !important;
|
||
}
|
||
```
|
||
|
||
### 3.3 代码组织
|
||
|
||
在 `style.css` 中重新组织文本效果样式：
|
||
|
||
```
|
||
/* ==========================================================================
|
||
文章文本特效（Text Effects in Articles）
|
||
========================================================================== */
|
||
|
||
/* ---------- 彩色黑幕（Color Curtain） ---------- */
|
||
/* 基础样式 */
|
||
/* 链接样式 */
|
||
/* 悬停样式 */
|
||
/* 夜间模式 */
|
||
|
||
/* ---------- 模糊文本（Text Blur） ---------- */
|
||
/* 基础样式 */
|
||
/* 悬停样式 */
|
||
|
||
/* ---------- 划掉文本（Strikethrough） ---------- */
|
||
/* 基础样式 */
|
||
/* 悬停样式 */
|
||
/* 夜间模式 */
|
||
```
|
||
|
||
## 4. 正确性属性（Correctness Properties）
|
||
|
||
### 4.1 加载动画属性
|
||
|
||
**Property 1.1**: 页面加载时必须显示加载动画
|
||
- **验证方式**：刷新页面，观察是否出现 SVG 圆环进度指示器
|
||
- **预期行为**：`DOMContentLoaded` 后显示，`window.load` 后隐藏
|
||
|
||
**Property 1.2**: PJAX 导航时必须显示加载动画
|
||
- **验证方式**：点击文章链接，观察是否出现加载动画
|
||
- **预期行为**：`pjax:start` 后显示，`pjax:end` 后隐藏
|
||
|
||
**Property 1.3**: 不存在旧的 `article-loading-overlay` 元素
|
||
- **验证方式**：检查 DOM 树和控制台
|
||
- **预期行为**：只有 `loading-overlay` 元素，无 `article-loading-overlay`
|
||
|
||
### 4.2 文本效果属性
|
||
|
||
**Property 2.1**: 文本效果在文章中可见
|
||
- **验证方式**：在文章中添加 `<span class="color-curtain">测试</span>`
|
||
- **预期行为**：文本被彩色背景遮盖
|
||
|
||
**Property 2.2**: 悬停时文本效果正确响应
|
||
- **验证方式**：鼠标悬停在文本效果上
|
||
- **预期行为**：
|
||
- `color-curtain`：显示文本内容
|
||
- `text-blur`：取消模糊
|
||
- `huhua`：颜色变深
|
||
|
||
**Property 2.3**: 夜间模式下颜色正确
|
||
- **验证方式**：切换到夜间模式，检查文本效果颜色
|
||
- **预期行为**：使用夜间模式专用颜色变量
|
||
|
||
## 5. 测试策略
|
||
|
||
### 5.1 单元测试（手动）
|
||
|
||
1. **页面初始加载**
|
||
- 刷新页面
|
||
- 观察加载动画是否正常显示和隐藏
|
||
- 检查控制台是否有错误
|
||
|
||
2. **PJAX 导航**
|
||
- 点击文章链接
|
||
- 观察加载动画是否正常显示和隐藏
|
||
- 检查页面内容是否正确更新
|
||
|
||
3. **文本效果显示**
|
||
- 在文章编辑器中添加测试内容：
|
||
```html
|
||
<span class="color-curtain">彩色黑幕测试</span>
|
||
<span class="text-blur">模糊文本测试</span>
|
||
<span class="huhua">划掉文本测试</span>
|
||
```
|
||
- 发布文章并查看效果
|
||
|
||
4. **文本效果交互**
|
||
- 鼠标悬停在每个文本效果上
|
||
- 验证交互行为是否正确
|
||
|
||
5. **夜间模式**
|
||
- 切换到夜间模式
|
||
- 重复步骤 3 和 4
|
||
|
||
### 5.2 回归测试
|
||
|
||
- 验证其他页面功能未受影响
|
||
- 验证移动端响应式布局正常
|
||
- 验证浏览器兼容性（Chrome、Firefox、Safari、Edge）
|
||
|
||
## 6. 风险评估
|
||
|
||
### 6.1 高风险
|
||
- **PJAX 功能失效**：移除旧代码可能影响 PJAX 导航
|
||
- **缓解措施**：仔细测试 PJAX 导航，确保新代码正确集成
|
||
|
||
### 6.2 中风险
|
||
- **样式冲突**：新增选择器可能与现有样式冲突
|
||
- **缓解措施**：使用 `!important` 确保优先级，参考黑幕样式的成功经验
|
||
|
||
### 6.3 低风险
|
||
- **性能影响**：新增选择器可能轻微影响 CSS 性能
|
||
- **缓解措施**：选择器数量有限，影响可忽略
|
||
|
||
## 7. 实施计划
|
||
|
||
### Phase 1: 清理旧加载动画代码
|
||
1. 备份 `argontheme.js`
|
||
2. 移除第 4970-5040 行旧代码
|
||
3. 添加 PJAX 集成代码
|
||
4. 测试页面加载和 PJAX 导航
|
||
|
||
### Phase 2: 修复文本效果样式
|
||
1. 备份 `style.css`
|
||
2. 重构 `color-curtain` 样式
|
||
3. 重构 `text-blur` 样式
|
||
4. 重构 `huhua` 样式
|
||
5. 添加夜间模式优化
|
||
6. 测试所有文本效果
|
||
|
||
### Phase 3: 验证和提交
|
||
1. 完整回归测试
|
||
2. 检查代码规范
|
||
3. 编写详细的 Git commit 信息
|
||
4. 提交代码
|
||
|
||
## 8. 成功标准
|
||
|
||
- ✅ 旧加载动画代码完全移除
|
||
- ✅ 页面加载和 PJAX 导航动画正常工作
|
||
- ✅ 所有文本效果在文章中正常显示和交互
|
||
- ✅ 夜间模式下颜色正确
|
||
- ✅ 无控制台错误或警告
|
||
- ✅ 代码遵循项目规范
|
||
- ✅ Git commit 信息详细清晰
|