本文详解 WordPress 项目中因 $(window).on("load") 事件绑定时机不当，导致预加载遮罩层（#loader）无法隐藏的常见问题，并提供稳定、兼容性强的解决方案。
本文详解 wordpress 项目中因 `$(window).on("load")` 事件绑定时机不当，导致预加载遮罩层（#loader）无法隐藏的常见问题，并提供稳定、兼容性强的解决方案。
在 WordPress 主题开发中，为提升用户体验，常通过
实现页面加载过渡效果。但如你所遇：遮罩层偶尔“卡住不消失”，控制台无报错，实际 DOM 已渲染完成——这通常不是逻辑错误，而是事件监听器注册时机与执行时机不匹配所致。
你的原始代码将 $(window).on("load", ...) 嵌套在 $(function() {...})（即 DOM Ready 回调）中：
$(function() {
$(window).on("load", function(){
$('#loader').css("display", "none", function() {
$(this).remove();
});
$('html, body').css('overflow', 'auto');
});
});⚠️ 问题根源：
- $(function(){...}) 在 DOM 构建完成后立即触发（等价于 DOMContentLoaded）；
- 而 $(window).on("load") 需等待所有资源（图片、样式表、字体、iframe 等）加载完毕才触发；
- 若 #loader 元素本身依赖的某外部资源（如 loader 图标 SVG、字体文件）加载异常或被缓存策略延迟，load 事件可能永不触发，造成“假死”；
- 更关键的是：WordPress 中 wp_body_open() 后可能动态注入脚本或资源，进一步延长 load 触发时机，甚至因某些插件干扰而失效。
✅ 推荐解法：放弃依赖 window.load，改用更可靠、更及时的 DOM 就绪 + 渲染完成双保险策略
Word 文档生成与编辑
下载
需要创建、读取、编辑或处理 Word 文档（.docx / .dotx）时使用。触发词：'Word'、'word 文档'、'.docx'、'生成报告'、'制作合同/简历/方案/说明书'、'提取 word 内容'、'在文档里查找替换'、'给文档加页眉页脚/目录/表格'。也用于把任意内容排版成一份正式的 Word 文件。不要用它处理 PDF、Excel 或无关编程任务。中文创作场景尤其适合：小说大纲稿、投稿文档、合同、简历、工作总结。
✅ 正确写法（推荐）
// custom.js —— 移除外层 $(function)，直接监听 window.load（更早注册）
$(window).on("load", function () {
const $loader = $('#loader');
if ($loader.length) {
$loader.fadeOut(300, function () {
$(this).remove();
});
}
$('html, body').css('overflow', 'auto');
});? 为什么这样更可靠？
- $(window).on("load", ...) 在全局作用域注册，不依赖 DOM Ready 的嵌套时序；
- 使用 .fadeOut() 替代 .css("display", "none") 提供平滑过渡并确保回调执行；
- 添加 if ($loader.length) 容错判断，避免 jQuery 在元素不存在时静默失败。
✅ 进阶增强方案（100% 确保隐藏）
若仍偶发失效（例如极端网络环境或第三方脚本阻塞），可叠加「超时兜底」机制：
$(window).on("load", function () {
hideLoader();
});
// 立即尝试隐藏（DOM 就绪后即执行）
$(function () {
setTimeout(hideLoader, 100); // 100ms 后强制尝试
});
function hideLoader() {
const $loader = $('#loader');
if ($loader.length) {
$loader.stop(true, true).fadeOut(250, function () {
$(this).remove();
});
}
$('html, body').css('overflow', 'auto');
}? 关键改进点：
- setTimeout(..., 100) 提供快速响应，避免用户感知等待；
- .stop(true, true) 清除可能堆积的动画队列，防止闪烁或卡顿；
- 函数封装提升可维护性，便于后续扩展（如添加性能埋点）。
? 注意事项
- 确保 #loader 位于 开头、wp_body_open() 之前（如你 header.php 所示），否则可能被 PHP 动态内容覆盖或延迟插入；
- 避免在 #loader 上设置 opacity: 0 或 visibility: hidden 等 CSS 隐藏方式——jQuery fadeOut() 依赖 display 属性，CSS 隐藏会干扰动画逻辑；
- 如使用 Webpack/Vite 等构建工具，请确认 jQuery 已正确暴露为全局 $，或改用原生 window.addEventListener('load', ...) 写法以减少依赖。
通过以上调整，你的加载遮罩层将稳定、即时、优雅地退出，彻底告别“无限 loading”困扰。
