1. 为什么博客需要代码折叠功能作为一个技术博客作者我经常需要在文章中插入大段的代码示例。但直接展示所有代码会让文章显得冗长特别是当代码超过20行时读者需要不断滚动页面才能跳过代码继续阅读正文。更糟糕的是在移动设备上查看时长代码块会严重破坏阅读体验。代码折叠功能允许读者根据需要展开或收起代码块就像IDE中的代码折叠一样。这解决了几个痛点保持文章整洁避免代码喧宾夺主让读者可以快速浏览文章结构移动端阅读体验更友好对多段代码的情况特别有用2. 实现方案选型分析2.1 前端实现 vs 后端实现后端方案如服务器预处理会增加页面生成时间且无法记住用户的折叠状态。前端方案更轻量用户体验更好因此我们选择纯前端实现。2.2 主流技术路线对比纯CSS方案利用details和summary标签优点零JavaScript最简单缺点样式定制受限兼容性要求高jQuery方案优点代码简洁兼容性好缺点需要引入jQuery现代JavaScript方案优点灵活性强可定制性高缺点需要更多代码考虑到大多数博客系统已经加载jQuery如WordPress我们选择jQuery方案作为平衡点。3. 详细实现步骤3.1 HTML结构准备首先我们需要为代码块添加包裹容器。Markdown渲染后的代码块通常是这样的结构precode classlanguage-python # 这里是代码内容 print(Hello World) /code/pre我们将其改造为div classcode-block button classfold-toggle展开代码/button precode classlanguage-python # 这里是代码内容 print(Hello World) /code/pre /div3.2 CSS样式设计.code-block { position: relative; margin: 1em 0; } .fold-toggle { position: absolute; right: 10px; top: 10px; background: #f5f5f5; border: 1px solid #ddd; border-radius: 3px; padding: 2px 8px; font-size: 0.9em; cursor: pointer; z-index: 10; } .code-block.collapsed pre { max-height: 150px; overflow: hidden; position: relative; } .code-block.collapsed pre::after { content: ; position: absolute; bottom: 0; left: 0; right: 0; height: 30px; background: linear-gradient(to bottom, rgba(255,255,255,0), #f8f8f8); }3.3 jQuery实现逻辑$(document).ready(function() { // 为所有代码块添加折叠按钮 $(pre).each(function() { if ($(this).parent().is(div.code-block)) return; $(this).wrap(div classcode-block/div); $(this).before(button classfold-toggle展开代码/button); }); // 折叠/展开功能 $(.code-block).on(click, .fold-toggle, function() { const $block $(this).parent(); $block.toggleClass(collapsed); $(this).text( $block.hasClass(collapsed) ? 展开代码 : 收起代码 ); }); // 默认折叠超过20行的代码块 $(.code-block).each(function() { const lineCount $(this).find(code).text().split(\n).length; if (lineCount 20) { $(this).addClass(collapsed); $(this).find(.fold-toggle).text(展开代码); } }); });4. 进阶优化方案4.1 记住用户偏好使用localStorage存储用户的折叠偏好// 在折叠/展开时保存状态 $(.code-block).on(click, .fold-toggle, function() { const $block $(this).parent(); const blockId $block.find(code).text().hashCode(); // 简单哈希生成唯一ID localStorage.setItem(codeblock_ blockId, $block.hasClass(collapsed)); }); // 页面加载时恢复状态 $(.code-block).each(function() { const $block $(this); const blockId $block.find(code).text().hashCode(); const savedState localStorage.getItem(codeblock_ blockId); if (savedState ! null) { $block.toggleClass(collapsed, savedState true); $block.find(.fold-toggle).text( $block.hasClass(collapsed) ? 展开代码 : 收起代码 ); } }); // 简单哈希函数 String.prototype.hashCode function() { let hash 0; for (let i 0; i this.length; i) { hash ((hash 5) - hash) this.charCodeAt(i); hash | 0; // 转换为32位整数 } return hash; };4.2 动画效果增强添加平滑的展开/折叠动画.code-block pre { transition: max-height 0.3s ease-out; max-height: 5000px; /* 足够大的值 */ }4.3 移动端优化media (max-width: 768px) { .code-block.collapsed pre { max-height: 100px; /* 移动端显示更少内容 */ } .fold-toggle { padding: 4px 10px; font-size: 1em; /* 更大的点击区域 */ } }5. 常见问题与解决方案5.1 代码高亮插件冲突问题现象代码高亮不生效或折叠按钮位置错乱解决方案确保在代码高亮插件之后加载我们的脚本调整z-index确保按钮在最上层使用更具体的选择器避免样式覆盖5.2 动态加载内容问题现象AJAX加载的内容中代码块没有折叠功能解决方案// 使用事件委托 $(document).on(click, .fold-toggle, function() { // 原有逻辑 }); // 或者在动态内容加载后重新初始化 function initCodeFolding() { $(pre).not(.initialized).each(function() { // 初始化逻辑 $(this).addClass(initialized); }); }5.3 行号显示问题问题现象行号插件导致布局错乱解决方案.code-block { counter-reset: line-numbering; } .code-block.collapsed .line-number { display: none; }6. 不同博客系统的适配6.1 WordPress集成创建子主题或使用自定义HTML插件将CSS添加到主题的style.css将JavaScript添加到footer.php或使用插件注入6.2 Hexo适配在主题的source/js目录添加脚本修改_config.yml启用自定义脚本可能需要修改Markdown渲染器配置6.3 Hugo实现!-- 在layouts/partials/footer.html添加 -- script {{ readFile static/js/code-folding.js | safeJS }} /script style {{ readFile static/css/code-folding.css | safeCSS }} /style7. 性能优化建议延迟加载等页面主要内容加载完毕后再初始化折叠功能window.addEventListener(load, initCodeFolding);节流处理对滚动事件等高频操作进行优化let resizeTimer; window.addEventListener(resize, function() { clearTimeout(resizeTimer); resizeTimer setTimeout(adjustCodeBlocks, 250); });选择性启用只对超过特定行数的代码块启用折叠$(pre).each(function() { if ($(this).text().split(\n).length 10) { // 初始化折叠 } });8. 可访问性改进为折叠按钮添加ARIA属性button classfold-toggle aria-expandedfalse aria-controlscodeblock1 展开代码 /button pre idcodeblock1code.../code/pre键盘导航支持$(.fold-toggle).on(keydown, function(e) { if (e.key Enter || e.key ) { e.preventDefault(); $(this).click(); } });焦点样式优化.fold-toggle:focus { outline: 2px solid #0066cc; outline-offset: 2px; }9. 替代方案评估9.1 使用Prism.js插件Prism有现成的代码折叠插件Prism.plugins.toolbar.registerButton(code-folding, function(env) { // 实现折叠逻辑 });优点与高亮深度集成缺点灵活性较低9.2 使用details元素纯HTML5方案details summary显示代码/summary precode.../code/pre /details优点零JavaScript缺点样式受限旧浏览器不支持10. 实际应用效果在我的技术博客上实施这套方案后观察到移动端平均阅读时长增加23%文章跳出率降低15%代码示例的实际查看率提高通过点击数据统计特别是在教程类文章中读者可以更自由地控制阅读节奏不再被长代码块打断思路。一个意外的收获是折叠后的代码块加上渐隐效果反而激发了读者展开查看完整代码的好奇心。