<img> 加載是異步的。若需在圖片**完全載入**後執行邏輯(如獲取真實尺寸、啟動動畫、隱藏 Loading),必須監聽 load 事件,並處理**緩存命中導致事件不觸發**的邊界情況。
function onImageLoad(src, callback) {
var img = new Image();
img.onload = function () { callback(null, img); };
img.onerror = function () { callback(new Error('Failed to load ' + src)); };
img.src = src; // 觸發加載
}
// 使用
onImageLoad('photo.jpg', function (err, img) {
if (err) return console.error(err);
console.log('尺寸:', img.naturalWidth, 'x', img.naturalHeight);
document.body.appendChild(img);
});
若圖片已在瀏覽器緩存,設置 src 後 onload **可能同步觸發**(現代瀏覽器)或**完全不觸發**(舊瀏覽器)。通用安全模式:
function safeOnLoad(img, callback) {
// 1. 已完成加載(緩存)
if (img.complete && img.naturalWidth !== 0) {
// 微任務延遲,保證回調順序一致性
Promise.resolve().then(function () { callback(null, img); });
return;
}
// 2. 正常監聽
img.onload = function () { img.onload = img.onerror = null; callback(null, img); };
img.onerror = function () { img.onload = img.onerror = null; callback(new Error('Load failed')); };
}
// 使用
var img = new Image();
safeOnLoad(img, function (err, img) { ... });
img.src = 'photo.jpg';
/**
* 等待容器內所有 <img> 加載完成
* @param {Element|jQuery} $container - 容器元素
* @param {Function} callback - 完成回調
* @param {Number} [timeout=30000] - 超時毫秒數
*/
function whenImagesLoaded($container, callback, timeout) {
timeout = timeout || 30000;
var $imgs = $container.find ? $container.find('img') : $container.querySelectorAll('img');
var total = $imgs.length;
var loaded = 0;
var timer;
var done = false;
if (total === 0) return callback();
function check() {
if (++loaded === total) finish();
}
function finish() {
if (done) return;
done = true;
clearTimeout(timer);
callback();
}
$imgs.forEach ? $imgs.forEach(bind) : Array.prototype.forEach.call($imgs, bind);
function bind(img) {
if (img.complete && img.naturalWidth !== 0) {
check();
} else {
img.onload = img.onerror = check;
}
}
timer = setTimeout(finish, timeout); // 兜底防卡死
}
// jQuery 版
$.fn.imagesLoaded = function (callback) {
whenImagesLoaded(this, callback);
return this;
};
// 使用
$('#gallery').imagesLoaded(function () {
console.log('相冊所有圖片就緒,啟動 Masonry 佈局');
initMasonry();
});
function appendImageAndWait(container, src, callback) {
var img = document.createElement('img');
img.src = src;
container.appendChild(img);
safeOnLoad(img, callback);
}
// 批量插入並等待全部完成
function appendImagesAndWait(container, srcArray, callback) {
var loaded = 0;
var total = srcArray.length;
var imgs = [];
srcArray.forEach(function (src) {
var img = document.createElement('img');
img.src = src;
container.appendChild(img);
imgs.push(img);
safeOnLoad(img, function () {
if (++loaded === total) callback(imgs);
});
});
}
loading="lazy" + decode()<!-- 瀏覽器原生懶加載 -->
<img src="large.jpg" loading="lazy" alt="...">
<script>
// 確保圖片解碼完成再顯示(避免佈局抖動)
async function showImage(img) {
try {
await img.decode(); // 返回 Promise,解碼完成才 resolve
img.classList.add('visible'); // CSS 控制 fade-in
} catch (e) {
console.warn('解碼失敗', e);
}
}
document.querySelectorAll('img[loading="lazy"]').forEach(function (img) {
if (img.complete) showImage(img);
else img.onload = function () { showImage(img); };
});
</script>
| 方案 | 適用場景 | 優點 | 缺點 |
|---|---|---|---|
原生 onload | 單圖、簡單頁面 | 零依賴 | 需手動處理緩存、錯誤、超時 |
whenImagesLoaded 工具函式 | 容器多圖、AJAX 插入內容後 | 統一管理、超時兜底 | 需維護計數邏輯 |
| imagesLoaded 庫 (desandro) | 複雜佈局、Masonry/Isotope 前置 | 成熟、支援背景圖、jQuery/原生雙模式 | ~5KB |
img.decode() + loading="lazy" | 現代瀏覽器、性能優先 | 原生、非阻塞主線程、硬體加速解碼 | Safari 15.4+ 支援 |
圖片加載回調看似簡單,**緩存命中、錯誤處理、超時兜底、批量協調** 才是工程化難點。建議專案統一封裝 ImageLoader 模組,內部用 Promise 包裝 safeOnLoad,對外暴露 load(src)、loadAll(src[])、waitFor(container) 三大介面,徹底屏蔽底層複雜度。