萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 腳本程式專題 >> JavaScript

JavaScript 圖片加載完成回調:單張/多圖/動態插入統一解決方案

核心問題

<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);
});

關鍵陷阱:緩存命中不觸發 onload

若圖片已在瀏覽器緩存,設置 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) 三大介面,徹底屏蔽底層複雜度。

copyright © 萬盛學電腦網 all rights reserved