argon-theme/.kiro/specs/loading-animation-cleanup/design.md

加载动画系统清理与文本效果修复 - 设计文档

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 页面初始加载

旧代码（需移除）：

// 第 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 实现步骤

1. 定位旧代码：确认第 4970-5040 行的完整范围
2. 移除旧代码：删除整个旧的加载动画实现
3. 添加 PJAX 支持：在 PageLoader 模块后添加 PJAX 事件监听
4. 测试验证：确保页面加载和 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 单元测试（手动）

1. 页面初始加载

   • 刷新页面
   • 观察加载动画是否正常显示和隐藏
   • 检查控制台是否有错误

2. PJAX 导航

   • 点击文章链接
   • 观察加载动画是否正常显示和隐藏
   • 检查页面内容是否正确更新

3. 文本效果显示

   • 在文章编辑器中添加测试内容：

     <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 信息详细清晰