9.4 KiB
9.4 KiB
加载动画系统清理与文本效果修复 - 设计文档
1. 架构概述
本次优化分为两个独立模块：
- 加载动画清理模块：移除旧代码，统一使用
PageLoader - 文本效果修复模块：为文本特效添加文章容器选择器支持
2. 加载动画清理设计
2.1 问题分析
旧代码位置：argontheme.js 第 4970-5040 行
旧代码特征：
- 使用
article-loading-overlayID - 手动创建 DOM 元素和骨架屏 HTML
- 使用
setInterval模拟进度 - 监听
window.load事件 - PJAX 事件处理中重复创建相同元素
新系统特征：
- 使用
PageLoader模块（IIFE 封装） - 统一的
loading-*类名前缀 - SVG 圆环进度指示器
- 智能进度算法（缓动函数）
- 延迟显示和最小显示时间控制
2.2 清理策略
2.2.1 页面初始加载
旧代码（需移除）：
// 第 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 加载动画
旧代码（需移除）：
// 第 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 实现步骤
- 定位旧代码：确认第 4970-5040 行的完整范围
- 移除旧代码：删除整个旧的加载动画实现
- 添加 PJAX 支持：在
PageLoader模块后添加 PJAX 事件监听 - 测试验证：确保页面加载和 PJAX 导航都正常
2.4 新增 PJAX 集成代码
// 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 问题分析
当前样式选择器：
.color-curtain { ... }
.text-blur { ... }
.huhua { ... }
问题：
- 缺少文章容器选择器（
article .entry-content、.article-content） - 在某些文章布局中可能不生效
3.2 修复策略
参考黑幕样式的修复方式，为每个文本效果添加文章容器选择器。
3.2.1 彩色黑幕（color-curtain）
当前样式：
.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;
/* ... */
}
修复方案：
/* 基础样式 */
.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;
}
夜间模式优化：
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）
当前样式：
.text-blur, .text-blur a, a .text-blur, .text-blur a.new {
filter: blur(2px) !important;
/* ... */
}
修复方案：
.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）
当前样式：
.huhua {
color: #9ea3a9 !important;
text-decoration: line-through !important;
/* ... */
}
修复方案：
.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;
}
夜间模式优化：
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 单元测试（手动）
-
页面初始加载
- 刷新页面
- 观察加载动画是否正常显示和隐藏
- 检查控制台是否有错误
-
PJAX 导航
- 点击文章链接
- 观察加载动画是否正常显示和隐藏
- 检查页面内容是否正确更新
-
文本效果显示
- 在文章编辑器中添加测试内容：
<span class="color-curtain">彩色黑幕测试</span> <span class="text-blur">模糊文本测试</span> <span class="huhua">划掉文本测试</span> - 发布文章并查看效果
- 在文章编辑器中添加测试内容：
-
文本效果交互
- 鼠标悬停在每个文本效果上
- 验证交互行为是否正确
-
夜间模式
- 切换到夜间模式
- 重复步骤 3 和 4
5.2 回归测试
- 验证其他页面功能未受影响
- 验证移动端响应式布局正常
- 验证浏览器兼容性（Chrome、Firefox、Safari、Edge）
6. 风险评估
6.1 高风险
- PJAX 功能失效：移除旧代码可能影响 PJAX 导航
- 缓解措施：仔细测试 PJAX 导航，确保新代码正确集成
6.2 中风险
- 样式冲突：新增选择器可能与现有样式冲突
- 缓解措施：使用
!important确保优先级，参考黑幕样式的成功经验
- 缓解措施：使用
6.3 低风险
- 性能影响：新增选择器可能轻微影响 CSS 性能
- 缓解措施：选择器数量有限，影响可忽略
7. 实施计划
Phase 1: 清理旧加载动画代码
- 备份
argontheme.js - 移除第 4970-5040 行旧代码
- 添加 PJAX 集成代码
- 测试页面加载和 PJAX 导航
Phase 2: 修复文本效果样式
- 备份
style.css - 重构
color-curtain样式 - 重构
text-blur样式 - 重构
huhua样式 - 添加夜间模式优化
- 测试所有文本效果
Phase 3: 验证和提交
- 完整回归测试
- 检查代码规范
- 编写详细的 Git commit 信息
- 提交代码
8. 成功标准
- ✅ 旧加载动画代码完全移除
- ✅ 页面加载和 PJAX 导航动画正常工作
- ✅ 所有文本效果在文章中正常显示和交互
- ✅ 夜间模式下颜色正确
- ✅ 无控制台错误或警告
- ✅ 代码遵循项目规范
- ✅ Git commit 信息详细清晰