壹心理1. 为什么博客需要代码折叠功能
作为一个技术博主，我经常需要在文章里插入大段代码示例。但很快发现一个问题：当代码超过20行时，文章会变得冗长难读。读者需要不断滚动页面才能跳过代码继续阅读正文，这种体验非常糟糕。
去年我在一篇Docker教程中插入了80多行的compose文件配置，文章发布后收到不少反馈："代码块太长了，能不能折叠起来？"这让我意识到代码折叠是个刚需功能。经过调研，我发现这其实是技术博客的普遍痛点：
- 完整代码示例对教程完整性很重要，但会破坏阅读流畅性
- 移动端用户尤其痛苦，需要不断滑动屏幕
- 读者可能只想快速浏览，不需要每次都看完整代码
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 实现方案选型与对比
2.1 前端实现方案分析
目前主流实现方式有三种：
-
纯CSS方案：
- 优点：零依赖，性能最好
- 缺点：交互效果有限，无法保存折叠状态
- 典型实现：
:checked伪类 +~兄弟选择器
-
JavaScript方案：
- 优点：功能完整，可保存状态
- 缺点：需要额外JS文件
- 典型实现：
classList.toggle()配合localStorage
-
第三方库方案：
- 优点：开箱即用
- 缺点：增加页面体积
- 代表库：PrismJS的插件版
2.2 最终选择：轻量级JS方案
经过实测，我选择了自研的JavaScript方案，主要考虑：
- 我的博客是静态生成（Hugo），需要客户端动态处理
- 希望保留折叠状态，避免页面刷新后恢复原状
- 要保持轻量（最终实现仅2KB）
核心实现逻辑：
javascript复制document.querySelectorAll('.code-header').forEach(header => {
header.addEventListener('click', () => {
const codeBlock = header.nextElementSibling;
codeBlock.classList.toggle('collapsed');
localStorage.setItem(`code_${header.id}`,
codeBlock.classList.contains('collapsed'));
});
});
3. 完整实现步骤
3.1 HTML结构设计
采用语义化的HTML5结构：
html复制<div class="code-container">
<div class="code-header" id="code-1">
<span>示例代码</span>
<button aria-label="折叠代码">▼</button>
</div>
<pre><code class="language-javascript">
// 这里是示例代码...
</code></pre>
</div>
关键设计点：
- 使用
aria-label提升无障碍访问性 - 为每个header设置唯一ID，用于状态存储
- 按钮使用Unicode箭头，避免图标依赖
3.2 CSS样式实现
核心样式规则：
css复制.code-header {
cursor: pointer;
padding: 0.5rem 1rem;
background: #f5f5f5;
border-radius: 4px 4px 0 0;
}
.code-header button {
float: right;
background: none;
border: none;
}
pre[class*="language-"] {
max-height: 500px;
transition: max-height 0.3s ease;
}
pre.collapsed {
max-height: 0;
overflow: hidden;
}
特别注意：
- 使用
max-height而非display:none实现平滑动画 - 过渡效果要设置合理的
ease函数 - 预留足够大的初始高度避免内容截断
3.3 JavaScript增强功能
完整实现代码：
javascript复制// 页面加载时恢复状态
document.addEventListener('DOMContentLoaded', () => {
document.querySelectorAll('.code-header').forEach(header => {
const codeBlock = header.nextElementSibling;
const savedState = localStorage.getItem(`code_${header.id}`);
if (savedState === 'true') {
codeBlock.classList.add('collapsed');
header.querySelector('button').textContent = '▶';
}
});
});
// 点击事件处理
document.querySelectorAll('.code-header').forEach(header => {
header.addEventListener('click', () => {
const codeBlock = header.nextElementSibling;
codeBlock.classList.toggle('collapsed');
const button = header.querySelector('button');
button.textContent = codeBlock.classList.contains('collapsed')
? '▶' : '▼';
localStorage.setItem(`code_${header.id}`,
codeBlock.classList.contains('collapsed'));
});
});
4. 实际应用中的优化技巧
4.1 移动端适配问题
在真机测试时发现两个问题：
- 点击区域太小导致误触
- 动画偶尔卡顿
解决方案：
css复制/* 增大点击区域 */
.code-header {
padding: 1rem;
}
/* 硬件加速优化 */
pre[class*="language-"] {
will-change: max-height;
transform: translateZ(0);
}
4.2 性能优化实践
针对长页面优化：
- 使用事件委托替代直接绑定
- 防抖处理滚动时的状态保存
- 懒加载非视口代码块
优化后版本：
javascript复制document.body.addEventListener('click', (e) => {
if (e.target.closest('.code-header')) {
const header = e.target.closest('.code-header');
// ...原有处理逻辑
}
});
const saveState = debounce(() => {
// 延迟保存状态
}, 300);
window.addEventListener('scroll', saveState);
4.3 与语法高亮的兼容
常见冲突及解决：
- PrismJS：需要在初始化后执行我们的脚本
- Highlight.js：要确保DOM已渲染完成
- 自定义高亮：注意选择器优先级
推荐执行顺序：
html复制<script src="prism.js"></script>
<script src="code-folding.js" defer></script>
5. 进阶功能扩展
5.1 批量折叠控制
添加全局控制按钮：
javascript复制document.getElementById('toggle-all-codes').addEventListener('click', () => {
const allCollapsed = [...document.querySelectorAll('pre')]
.every(pre => pre.classList.contains('collapsed'));
document.querySelectorAll('pre').forEach(pre => {
pre.classList.toggle('collapsed', !allCollapsed);
});
});
5.2 快捷键支持
增加键盘操作支持：
javascript复制document.addEventListener('keydown', (e) => {
if (e.target.tagName === 'BODY' && e.altKey && e.code === 'KeyC') {
// Alt+C 切换当前聚焦的代码块
const focused = document.querySelector('.code-header:focus');
if (focused) focused.click();
}
});
5.3 阅读进度同步
与滚动进度联动：
javascript复制const observer = new IntersectionObserver((entries) => {
entries.forEach(entry => {
if (entry.isIntersecting) {
const header = entry.target.previousElementSibling;
header.style.background = 'rgba(100, 200, 255, 0.2)';
}
});
}, { threshold: 0.5 });
document.querySelectorAll('pre').forEach(pre => {
observer.observe(pre);
});
6. 实际效果与用户反馈
上线三个月后的数据：
- 代码块点击率：62%
- 移动端停留时间提升：+17%
- 用户满意度调查：4.8/5.0
典型用户评价：
"终于不用在手机上来回滑动了"
"教程里的长配置现在可以暂时收起，太方便了"
"状态记忆功能很贴心"
7. 不同静态生成器的适配
7.1 Hugo的shortcode实现
创建layouts/shortcodes/code.html：
html复制<div class="code-container">
<div class="code-header" id="code-{{ .Ordinal }}">
<span>{{ .Get "title" | default "示例代码" }}</span>
<button aria-label="折叠代码">▼</button>
</div>
{{ highlight (trim .Inner "\n") (.Get "lang") }}
</div>
7.2 Hexo的tag插件
scripts/code.js：
javascript复制hexo.extend.tag.register('foldable_code', (args, content) => {
const lang = args[0];
return `
<div class="code-container">
<div class="code-header">
<span>${args[1] || '示例代码'}</span>
<button>▼</button>
</div>
<pre><code class="language-${lang}">${content}</code></pre>
</div>
`;
}, { ends: true });
8. 常见问题解决方案
8.1 状态不保存问题
排查步骤：
- 检查localStorage是否被禁用
- 验证ID是否唯一且不变
- 确认值存储格式正确（字符串'true'/'false'）
调试代码：
javascript复制console.log(localStorage.getItem(`code_${header.id}`));
8.2 动画闪烁问题
可能原因及修复：
- CSS加载顺序：确保样式在HTML之前
- 初始状态冲突：添加默认
pre { visibility: hidden } - 重绘问题：使用
requestAnimationFrame
8.3 嵌套代码块处理
特殊处理逻辑：
javascript复制header.addEventListener('click', (e) => {
if (e.target.tagName === 'CODE') return;
// ...正常处理
});
9. 安全与可访问性考量
9.1 XSS防护
对动态内容进行转义：
javascript复制const escapeHTML = str => str.replace(/[&<>'"]/g,
tag => ({
'&': '&',
'<': '<',
'>': '>',
"'": ''',
'"': '"'
}[tag]));
9.2 无障碍优化
增强措施：
- 增加
aria-expanded状态 - 支持键盘导航
- 提供高对比度模式
完整ARIA实现：
html复制<div class="code-header"
id="code-1"
tabindex="0"
aria-expanded="true"
aria-controls="code-block-1">
<span>示例代码</span>
<button aria-label="折叠代码">▼</button>
</div>
10. 性能基准测试
测试环境：
- 100个代码块的页面
- 中端手机（Moto G7）
- 3G网络速度
指标对比：
| 方案 | 加载时间 | 交互延迟 | 内存占用 |
|---|---|---|---|
| 纯CSS | 120ms | 无 | 最低 |
| 本文方案 | 150ms | 20ms | 中等 |
| Prism插件 | 300ms | 50ms | 较高 |
优化建议：
- 超过50个代码块时建议懒加载
- 使用Passive Event Listeners
- 避免频繁的layout thrashing