complete 是 <img> 元素的只读布尔属性,用于快照式判断图片当前是否加载完成(含成功、失败或空 src);其值为 true 时需结合 naturalWidth 判断是否真实加载成功,无法反映“加载中”状态,也不能替代 load/error 事件监听。

complete 不是 HTML5 的属性,也不是 JS 中某个通用函数——它只是 <img> 元素的一个只读布尔属性,用来判断图片是否已加载完成(含失败),仅此而已。
怎么判断图片是否加载完了?用 complete 看一眼就行
它不是事件、不是方法,就是一个快照式的状态标识。只要图片 DOM 节点存在,你随时可以读取它的 complete 值:
const img = document.querySelector('img');
console.log(img.complete); // true 或 false
但要注意:这个值只反映“当前时刻”的加载状态,不会自动更新,也不触发响应式行为。
-
complete为true:图片已成功加载、或加载失败(比如 404)、或本身就是空src(src="") -
complete为false:图片还没开始加载,或正在加载中(此时src已设但尚未触发网络请求或解析) - 动态设置
src后,complete不会立刻变true,得等加载结束(成功/失败)才更新
为什么 complete 在 onload 之前就返回 true?
因为浏览器可能从缓存直接取图,加载极快,DOM 创建完、src 赋值后,图片瞬间就“完成了”。这时候你如果在同步代码里查 complete,很可能得到 true,但 onload 还没触发(或者压根不触发,如果图片已缓存且尺寸未变)。
立即学习“前端免费学习笔记(深入)”;
- 不要依赖
complete来替代事件监听;它不能代替load或error - 想确保图片渲染就绪?必须监听
load和error;complete只适合做“快速探针”,比如预判要不要加 loading 占位符 - 服务端渲染(SSR)或静态 HTML 中的图片,服务端无法知道
complete,这个属性纯客户端运行时才有意义
complete 和 naturalWidth 配合看更靠谱
单看 complete 容易误判:它为 true 时,图片可能加载失败(如 404),此时 naturalWidth 是 0。所以安全做法是双检:
if (img.complete && img.naturalWidth !== 0) {
// 图片加载成功且有尺寸
} else if (img.complete) {
// 加载失败或为空 src
}
-
naturalWidth/naturalHeight在加载失败时通常为 0(Chrome/Firefox 行为一致) - IE11 会返回 1,但 IE 已淘汰,不用专门兼容
- 注意:即使
complete === true,若图片跨域且没配 CORS,naturalWidth可能被限制为 0(安全限制)
真正容易被忽略的是:你根本没法靠 complete 感知“加载中”状态——它只有两态(true/false),没有中间态。要实现 loading 效果,还是得靠显式控制,比如加 class、用 loading="lazy" 配合 IntersectionObserver,或者老老实实监听事件。










