本文详解 WordPress 项目中因 $(window).on("load") 绑定时机与执行逻辑不当，导致预加载遮罩层（#loader）无法隐藏或移除的常见故障，并提供稳定可靠的解决方案。
本文详解 wordpress 项目中因 `$(window).on("load")` 绑定时机与执行逻辑不当，导致预加载遮罩层（#loader）无法隐藏或移除的常见故障，并提供稳定可靠的解决方案。
在 WordPress 主题开发中，使用全屏加载遮罩（如
根本原因在于你当前的 JavaScript 逻辑存在两个关键隐患：
重复绑定风险：$(function() { ... }) 是 jQuery 的 DOM ready 回调，而内部又注册了 $(window).on("load", ...)。若该脚本被多次引入（例如子主题复用、插件冲突、缓存异常或热重载），load 事件监听器会被重复添加，但仅首次触发后 #loader 被移除；后续监听器仍会执行，却因 $('#loader') 已不存在而静默失败——表面看是“卡住”，实则是逻辑失效。
-
.css("display", "none", callback) 语法错误：jQuery 的 .css() 方法不支持回调函数参数。你写的这段代码：
$('#loader').css("display", "none", function() { $(this).remove(); });将直接忽略第三个参数（回调），导致 #loader 仅被设为 display: none，但从未被真正移除，且 html, body 的 overflow 也未恢复。这正是“加载态永远存在”的技术根源。
word-chinese-automation下载中文 Word 文档自动化校对工具。当用户需要对中文文本或 Word 文档进行标点符号检查、语法检查、错别字检查时使用此 skill。触发词：语法检查、错别字、标点符号、校对、检查文档。
✅ 正确做法是：分离隐藏与移除操作，并确保仅执行一次。推荐以下健壮实现：
// custom.js —— 移除外层 $(function)，直接监听 load 事件（更精准）
$(window).on('load', function() {
const $loader = $('#loader');
if ($loader.length) {
$loader.fadeOut(300, function() {
$(this).remove();
});
$('html, body').css('overflow', 'auto');
}
});? 关键优化说明：
- 不包裹在 $(function()) 内：避免 DOM ready + window load 双重封装带来的不确定性；load 事件本身已保证所有资源（含图片、iframe）加载完毕，时机可靠。
- 显式检查元素存在：if ($loader.length) 防止因 HTML 结构变动或异步加载导致的空选择器错误。
- 使用 fadeOut() 替代 css(display:none)：既提供视觉过渡（可选），又天然支持回调，确保 remove() 在动画结束后执行。
- 统一恢复滚动：$('html, body').css('overflow', 'auto') 确保兼容各浏览器滚动行为。
⚠️ 额外注意事项：
- 检查 header.php 中 是否位于 最顶部（你当前结构正确），并确认未被其他 JS 动态插入或重复渲染；
- 若使用 Webpack/Vite 等构建工具，请确认 custom.js 未被多次 import 或 require；
- 建议在 functions.php 中使用 wp_enqueue_script() 正确加载脚本，并设置 'jquery' 为依赖，确保 jQuery 已就绪；
- 生产环境可进一步添加超时兜底机制（例如 5 秒后强制移除 loader），防止极端网络异常场景。
通过以上修正，你的加载遮罩将严格遵循“资源加载完成 → 平滑隐藏 → 彻底移除 → 恢复交互”的预期流程，彻底解决“无限加载”这一偶发却致命的体验缺陷。
