怎么使用原生JS监听页面加载完成事件
本文详细讲解如何使用原生JavaScript监听页面加载完成事件,深入分析DOMContentLoaded与window.load的核心差异、标准实现步骤、document.readyState状态机容错处理及常见踩坑规避。
DOMContentLoaded 与 window.load 两个核心事件:如果只需要操作 HTML 节点和绑定用户交互,应优先在 document 上监听 DOMContentLoaded 事件;如果必须等待页面中的所有外部图片、样式表和子框架完全加载,则在 window 上监听 load 事件。此外,对于可能延迟执行的异步脚本,还应结合 document.readyState 状态进行前置判断,防止因事件早已触发而漏听。
一、核心事件辨析:DOMContentLoaded 与 load 的差异与选择
很多初学者容易将“页面加载完成”笼统地理解为一个单一时间点,但在浏览器的实际渲染机制中,文档的解析与外部资源的加载是分阶段进行的。准确理解两个核心事件的触发时机,是写出高性能、无闪烁前端代码的前提。
1. DOMContentLoaded:DOM 树构建就绪
DOMContentLoaded 事件绑定在 document 对象上。当浏览器下载完初始 HTML 并将其解析成完整的 DOM 树结构后,该事件就会立即触发。此时,浏览器无需等待外部样式表(CSS)、图片、音视频或 <iframe> 等资源下载完毕。
在绝大多数日常交互开发中,只要 DOM 节点已经存在,即可执行元素查找、事件监听绑定、选项卡初始化等业务。使用该事件可以让脚本尽早执行,极大减少用户等待可交互界面的时间。
2. window.load:全资源完全加载完毕
load 事件绑定在 window 对象上。只有当 HTML 文档、所有依赖的外部 CSS 文件、外链脚本、图片、Web 字体以及嵌入的子框架(iframe)全部完成下载、解码并就绪后,该事件才会触发。
如果业务逻辑需要读取图片的自然宽度与高度(naturalWidth / naturalHeight)、利用 Canvas 绘制已加载的位图、或者收集首屏全量渲染性能耗时,就必须等待 window.load 事件。
二、原生 JS 监听加载完成的标准实现步骤
在编写原生监听代码时,推荐统一采用 W3C 标准的 addEventListener 方法,避免使用传统的属性赋值(如 window.onload = fn),以确保多个功能模块之间的事件监听不会相互覆盖。
步骤 1:明确业务依赖的时机
首先判断初始化逻辑是否依赖图片等外部媒体资源的真实尺寸或渲染效果:
- 仅依赖 DOM 元素:如查找按钮绑定
click、添加弹窗节点、初始化表单验证,选择DOMContentLoaded。 - 依赖外部多媒体与排版资源:如页面截图生成、图片轮播高度测量、第三方 SDK 完整挂载检测,选择
load。
步骤 2:使用 addEventListener 进行标准绑定
针对不同时机,编写标准监听代码。代码示例如下:
// 方式 A:等待 DOM 树构建完成即执行(推荐大多数场景)
document.addEventListener('DOMContentLoaded', function () {
console.log('DOM 树已构建就绪,可以安全操作 DOM 元素');
const submitBtn = document.getElementById('submit-btn');
if (submitBtn) {
submitBtn.addEventListener('click', () => {
console.log('按钮点击事件已生效');
});
}
});
// 方式 B:等待整个页面所有外部资源(图片、样式等)完全加载完毕
window.addEventListener('load', function () {
console.log('整个页面及所有外部静态资源加载完毕');
const bannerImg = document.querySelector('.banner-img');
if (bannerImg) {
console.log('图片实际渲染宽度:', bannerImg.offsetWidth);
console.log('图片原始物理尺寸:', bannerImg.naturalWidth, bannerImg.naturalHeight);
}
});
DOMContentLoaded 事件的派发目标是 document,不要写成 window.addEventListener('DOMContentLoaded', ...)(虽然部分现代浏览器兼容此写法,但遵循规范绑定在 document 更具确定性);同样地,load 事件应绑定在 window 上。
三、避免踩坑:异步脚本(async/defer)与 readyState 状态机
在现代前端开发中,脚本通常被声明为 defer、async,或者由前端微模块在运行时动态通过 document.createElement('script') 注入页面。此时,脚本执行的时刻可能已经晚于浏览器分发事件的时间点。
如果脚本执行时,DOMContentLoaded 或 load 已经触发完毕,此时再去通过 addEventListener 注册监听器,该回调函数将永远不会被触发,进而引发页面功能卡死或初始化失效的故障。
1. 理解 document.readyState 的三种状态
浏览器提供了 document.readyState 属性,用以实时反映当前文档的加载进度,它包含以下三个离散值:
"loading":文档仍在下载与初步解析,DOM 树未构建完成。"interactive":HTML 解析完毕,DOM 树已构建完成并可进行交互操作。此时会派发DOMContentLoaded事件。"complete":页面所有图片、框架、字体及辅助资源均已完成加载。此时会派发window.load事件。
2. 封装自适应高可靠就绪函数
为彻底解决异步脚本“漏听”事件的问题,工业级代码应先检查 document.readyState。如果状态已经越过了阶段点,则立即同步或微任务执行回调;若仍处于 loading 阶段,再挂载事件监听器。
/**
* 安全的 DOM 就绪监听函数(无论脚本何时执行,均能保证回调被调用)
* @param {Function} callback DOM 就绪后的执行逻辑
*/
function onDomReady(callback) {
if (typeof callback !== 'function') return;
// 如果已经解析完成或已完全加载,直接执行
if (document.readyState !== 'loading') {
// 使用 requestAnimationFrame 或 queueMicrotask 确保异步时序一致
queueMicrotask(callback);
} else {
// 仍在解析阶段,正常监听 DOMContentLoaded
document.addEventListener('DOMContentLoaded', callback, { once: true });
}
}
/**
* 安全的页面全量资源就绪监听函数
* @param {Function} callback 全量就绪后的执行逻辑
*/
function onPageFullyLoaded(callback) {
if (typeof callback !== 'function') return;
// 若整页已处于 complete 状态,直接触发
if (document.readyState === 'complete') {
queueMicrotask(callback);
} else {
window.addEventListener('load', callback, { once: true });
}
}
// 使用示例
onDomReady(() => {
console.log('无论该脚本是同步、异步还是动态插入,此逻辑必定安全执行');
});
四、常见开发误区与排查清单
在日常监听页面加载事件的过程中,有以下几个典型误区需要重点规避:
-
使用传统 DOM0 级属性导致监听器被覆盖:
写法如
window.onload = function() { ... }属于直接给对象的属性赋值。如果页面中引入的其他工具库或协同开发人员也写了window.onload = ...,先前的监听逻辑就会被无声无息地覆盖掉。请务必使用addEventListener,它支持给同一事件注册多个独立处理器。 -
在 DOMContentLoaded 中获取未设定宽高的图片尺寸:
在
DOMContentLoaded触发时,HTML 标签中的<img>节点已经在 DOM 树中建立,但图片二进制数据仍在网络传输或解码中。此时通过 JS 读取该图片的naturalWidth、naturalHeight通常返回 0。如果必须依赖图片尺寸做瀑布流或画板计算,应使用load事件,或者给单个图片对象单独监听img.addEventListener('load', ...)。 -
误在 readyState 为 interactive 时等待图片加载:
interactive仅代表 DOM 结构就绪,并不代表外部图片可用。需要全资源时,判断条件必须严格匹配document.readyState === 'complete'。
五、总结与技术选型指南
选择正确的页面加载事件能够平衡前端界面的响应速度与逻辑执行的准确度。下表总结了原生 JS 中涉及加载完成的关键机制:
| 机制 / 事件名称 | 绑定目标 | 触发时机 | 适用业务场景 | 推荐等级 |
|---|---|---|---|---|
| DOMContentLoaded | document |
HTML 解析完毕、DOM 树构建完成 | 节点查找、事件代理绑定、常规 UI 逻辑初始化 | 优先推荐 |
| window.load | window |
页面本身及全部外部资源下载完毕 | 图片尺寸计算、Canvas 绘制、整页渲染耗时性能埋点 | 特定按需 |
| readystatechange | document |
readyState 属性每次发生变更时 | 精细化监控加载进度、异步加载脚本的保底状态守卫 | 辅助进阶 |
技术选型决策路径:
- 如果你的代码是一般交互脚本,且放置在 HTML 头部,优先使用
document.addEventListener('DOMContentLoaded', handler)。 - 如果你的脚本放在
<body>标签的最底部(如</body>之前),且不带async属性,此时执行时 DOM 已经解析完毕,实际上直接执行初始化代码即可,也可包一层DOMContentLoaded增加可维护性。 - 如果你的脚本是作为第三方 SDK、异步模块或动态注入脚本,务必先通过
document.readyState !== 'loading'进行状态判断,在就绪时立即执行,未就绪时再注册监听,彻底杜绝任何时序边缘风险。
JS原生实现元素淡入淡出效果的基础代码
2026-11-16 13:42:41
JavaScript怎么设置自定义鼠标光标图片
2026-11-16 13:24:23
Browser Use 1.0.2排查顺序:固定依赖、查询版本与区分CDP等待和页面阻塞
2026-11-16 11:27:48
用JavaScript动态创建DOM元素构建测试网页
2026-11-13 11:51:34
JavaScript将表单数据序列化为JSON格式的方法
2026-11-13 10:42:12








