jQuery.holdReady() 方法（建议收藏）

jQuery.holdReady() 方法：掌控脚本加载时机的“暂停按钮”

在前端开发中，我们常常遇到一个尴尬的问题：页面刚加载完，DOM 还没完全准备好，但我们的 jQuery 代码却已经执行了。结果呢？报错、逻辑失效、页面卡顿，用户体验大打折扣。这时候，你就需要一个“等待机制”——让 jQuery 暂停执行，直到你明确告诉它“可以开始了”。

jQuery 提供了这样一个精准控制加载时机的工具：jQuery.holdReady() 方法。它就像一个临时的“暂停开关”，允许你在页面初始化阶段，延后 jQuery 的 ready 事件触发，直到你准备好所有资源。

为什么需要 jQuery.holdReady() 方法？

想象一下，你正在搭建一个复杂的网页，里面加载了多个第三方脚本，比如地图 API、图表库、广告 SDK。这些脚本可能需要几秒甚至更长时间才能加载完成。如果 jQuery 的 $(document).ready() 一上来就执行，而这些依赖还没就绪，代码岂不是会“空转”？

举个例子：

<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
<script>
  // ❌ 错误：地图库还没加载，却调用了地图相关方法
  $(document).ready(function() {
    console.log("页面已就绪");
    initMap(); // 报错！initMap 未定义
  });
</script>

这就是典型的“提前执行”问题。jQuery.holdReady() 方法正是为了解决这类问题而生。

jQuery.holdReady() 方法语法与原理

jQuery.holdReady() 是 jQuery 提供的一个静态方法，用于延迟 $(document).ready() 的触发，直到你调用 jQuery.holdReady(false) 来释放控制。

语法结构

jQuery.holdReady(true);   // 暂停 ready 事件
jQuery.holdReady(false);  // 恢复 ready 事件

原理说明

当你调用 jQuery.holdReady(true) 时，jQuery 会记录一个“等待标志”。
此时，即使 DOM 已就绪，$(document).ready() 也不会立即执行。
只有当所有“等待”任务完成，并且你调用 jQuery.holdReady(false) 后，jQuery 才会触发 ready 事件。

这就像在启动火箭前，必须先完成所有系统自检。holdReady(true) 就是“自检中”，holdReady(false) 就是“自检通过，点火发射”。

实际应用：延迟加载第三方库

我们来通过一个真实场景演示如何使用 jQuery.holdReady() 方法。

场景需求

我们要在页面中加载 Google Maps API，并在 DOM 就绪后初始化地图。但地图 API 加载时间不确定，不能依赖 $(document).ready()。

完整代码示例

<!DOCTYPE html>
<html lang="zh">
<head>
  <meta charset="UTF-8" />
  <title>jQuery.holdReady() 实战</title>
  <script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
</head>
<body>
  <div id="map" style="width: 600px; height: 400px; border: 1px solid #ccc;"></div>
  <script>
    // ✅ 第一步：调用 holdReady(true)，暂停 ready 事件
    // 这样能防止后续代码在地图库未加载时提前执行
    jQuery.holdReady(true);

    // ✅ 第二步：动态加载 Google Maps API
    // 通过 script 标签异步加载，设置 callback
    const script = document.createElement('script');
    script.src = 'https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap';
    script.async = true;
    document.head.appendChild(script);

    // ✅ 第三步：定义地图初始化函数
    // 注意：这个函数必须是全局的，因为 Google Maps 会调用它
    window.initMap = function() {
      console.log("Google Maps API 已加载完成");

      // ✅ 第四步：一旦地图库就绪，释放 holdReady
      // 这时 jQuery 才会触发 ready 事件
      jQuery.holdReady(false);

      // ✅ 第五步：现在可以安全使用 jQuery 和地图 API
      $(document).ready(function() {
        console.log("DOM 已就绪，且地图库已加载");
        
        // 创建地图实例
        const map = new google.maps.Map(document.getElementById('map'), {
          zoom: 12,
          center: { lat: 37.7749, lng: -122.4194 }
        });

        // 添加标记
        new google.maps.Marker({
          position: { lat: 37.7749, lng: -122.4194 },
          map: map,
          title: '旧金山'
        });
      });
    };

    // ✅ 可选：添加错误处理
    script.onerror = function() {
      console.error("Google Maps API 加载失败");
      jQuery.holdReady(false); // 即使失败，也要释放，避免无限等待
    };
  </script>
</body>
</html>

代码解析

jQuery.holdReady(true)：在加载外部脚本前先“锁住” jQuery 的 ready 事件。
script.src = 'https://maps.googleapis.com/maps/api/js?key=...&callback=initMap'：异步加载地图库，通过 callback 回调通知加载完成。
window.initMap：必须是全局函数，否则 Google Maps 无法调用。
jQuery.holdReady(false)：在 initMap 中调用，释放等待状态。
$(document).ready()：此时才真正执行，因为依赖已满足。

高级技巧：多个资源并行加载

在复杂项目中，你可能需要等待多个资源就绪，比如：地图库 + 图表库 + 用户认证服务。

多资源等待策略

// ✅ 开始等待
jQuery.holdReady(true);

let resourcesLoaded = 0;
const totalResources = 3;

// 1. 加载图表库
loadScript('https://cdn.jsdelivr.net/npm/chart.js@3.9.1/dist/chart.min.js', function() {
  resourcesLoaded++;
  checkAllLoaded();
});

// 2. 加载用户认证服务
loadScript('https://auth.example.com/api/v1/init.js', function() {
  resourcesLoaded++;
  checkAllLoaded();
});

// 3. 加载地图库
loadScript('https://maps.googleapis.com/maps/api/js?key=XXX&callback=onMapReady', function() {
  resourcesLoaded++;
  checkAllLoaded();
});

// ✅ 辅助函数：检查所有资源是否加载完成
function checkAllLoaded() {
  if (resourcesLoaded === totalResources) {
    jQuery.holdReady(false); // 释放等待
    console.log("所有资源加载完成，触发 ready 事件");
  }
}

// ✅ 工具函数：动态加载脚本
function loadScript(src, callback) {
  const script = document.createElement('script');
  script.src = src;
  script.onload = callback;
  script.onerror = function() {
    console.warn('脚本加载失败:', src);
    callback(); // 即使失败也通知
  };
  document.head.appendChild(script);
}

这种模式非常适用于现代前端应用，尤其是 SPA（单页应用）中资源预加载的场景。

常见误区与注意事项

误区	正确做法	说明
在 `$(document).ready()` 内调用 `holdReady(true)`	一定要在 `ready()` 之前调用	否则无效，因为 ready 已经触发
忘记调用 `holdReady(false)`	必须在所有依赖完成后释放	否则页面会永远“卡住”
把 `holdReady(false)` 放在错误的位置（如 setTimeout 中）	放在依赖加载完成的回调里	确保时机准确
在非全局作用域定义 callback 函数	必须使用 `window.xxx` 声明	否则外部脚本无法调用

与现代技术的对比：为何仍需 holdReady？

随着 import 和 async/await 的普及，很多人会问：现在还用 jQuery.holdReady() 吗？

答案是：在特定场景下依然非常有用。

遗留项目：很多企业项目仍在使用 jQuery，holdReady() 是唯一可靠的延迟机制。
动态脚本加载：当依赖是外部 CDN，且无法控制加载顺序时，holdReady() 是最简洁的方案。
兼容性：相比 Promise.all() 或 async/await，它更轻量，无需修改整个执行流。

总结与建议

jQuery.holdReady() 方法虽然不常被提及，但在处理异步资源加载时，它是一把“精准的手术刀”。它能让你的代码在依赖就绪后再执行，避免空指针、逻辑错误和用户体验下降。

使用场景：加载外部脚本（地图、支付 SDK、广告库等）。
核心原则：先 hold，后 release。
重要提醒：必须成对使用，否则页面将无法响应。

如果你正在维护一个基于 jQuery 的项目，尤其是涉及第三方 API 的项目，强烈建议将 jQuery.holdReady() 方法纳入你的基础工具库中。

记住：好的前端代码，不只写得快，更要写得稳。而 jQuery.holdReady() 方法，正是这份“稳”的关键一环。