萬盛學電腦網

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

jQuery 圖片預載入完整指南:基本用法、進度回呼、錯誤處理與懶載入整合

圖片預載入能顯著提升頁面感知效能,避免「佈局跳動」與「白屏等待」。本文從基礎單張預載到批次管理、進度條、錯誤重試、IntersectionObserver 懶載入整合,提供完整可複用的工具函數與最佳實踐。

核心原理

const img = new Image();
img.onload = () => { /* 成功 */ };
img.onerror = () => { /* 失敗 */ };
img.src = url; // 觸發下載

關鍵點:先綁事件、再設 src,否則快取命中時 onload 可能不觸發。

1. 單張預載入 Promise 封裝

function preloadImage(src, { timeout = 10000, crossOrigin } = {}) {
  return new Promise((resolve, reject) => {
    const img = new Image();
    if (crossOrigin) img.crossOrigin = crossOrigin;
    const timer = setTimeout(() => {
      img.onload = img.onerror = null;
      reject(new Error(`Timeout: ${src}`));
    }, timeout);

    img.onload = () => {
      clearTimeout(timer);
      resolve({ img, src, width: img.naturalWidth, height: img.naturalHeight });
    };
    img.onerror = (e) => {
      clearTimeout(timer);
      reject(new Error(`Load failed: ${src}`));
    };
    img.src = src;
  });
}

// 使用
preloadImage('https://example.com/hero.jpg')
  .then(({ img }) => document.body.appendChild(img))
  .catch(console.error);

2. 批次預載入(支援進度、並發控制、錯誤繼續)


/**
 * @param {string[]} sources 圖片 URL 陣列
 * @param {Object} options
 *   - concurrency: 同時下載數 (預設 4)
 *   - onProgress: (loaded, total, currentSrc) => void
 *   - onComplete: (results) => void
 *   - onError: (error, src) => void
 * @returns {Promise<{success: [], failed: []}>}
 */
async function preloadImages(sources, options = {}) {
  const { concurrency = 4, onProgress, onComplete, onError } = options;
  const results = { success: [], failed: [] };
  const queue = [...sources];
  let loaded = 0;

  async function worker() {
    while (queue.length) {
      const src = queue.shift();
      try {
        const res = await preloadImage(src);
        results.success.push(res);
      } catch (err) {
        results.failed.push({ src, error: err.message });
        onError?.(err, src);
      }
      loaded++;
      onProgress?.(loaded, sources.length, src);
    }
  }

  await Promise.all(Array.from({ length: Math.min(concurrency, sources.length) }, worker));
  onComplete?.(results);
  return results;
}

// 使用範例
const urls = Array.from({ length: 20 }, (_, i) => `https://picsum.photos/seed/${i}/800/600`);
preloadImages(urls, {
  concurrency: 6,
  onProgress: (loaded, total, src) => console.log(`${loaded}/${total} - ${src}`),
  onComplete: (r) => console.log(`完成:成功 ${r.success.length},失敗 ${r.failed.length}`)
});

3. jQuery 版:預載後淡入插入容器


$.fn.preloadAndFadeIn = function (urls, options = {}) {
  const $container = this;
  const { delay = 100, duration = 400 } = options;
  
  preloadImages(urls).then(({ success }) => {
    success.forEach(({ img }, i) => {
      setTimeout(() => {
        $(img).hide().appendTo($container).fadeIn(duration);
      }, i * delay);
    });
  });
};

// 使用
$('#gallery').preloadAndFadeIn([
  'img/1.jpg', 'img/2.jpg', 'img/3.jpg'
]);

4. 懶載入整合(IntersectionObserver + 預載佇列)


class LazyImageLoader {
  constructor(options = {}) {
    this.options = {
      rootMargin: '200px 0px', // 提前 200px 開始載入
      threshold: 0.01,
      placeholder: 'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7',
      ...options
    };
    this.observer = new IntersectionObserver(this._onIntersect.bind(this), this.options);
    this.cache = new Map(); // src -> Promise
  }

  observe(imgEl) {
    if (!(imgEl instanceof HTMLImageElement)) return;
    const src = imgEl.dataset.src;
    if (!src) return;
    imgEl.src = this.options.placeholder;
    this.observer.observe(imgEl);
    // 預先放入快取,避免重複請求
    if (!this.cache.has(src)) {
      this.cache.set(src, preloadImage(src).catch(() => null));
    }
  }

  async _onIntersect(entries) {
    for (const entry of entries) {
      if (!entry.isIntersecting) continue;
      const img = entry.target;
      const src = img.dataset.src;
      this.observer.unobserve(img);
      try {
        const { img: loadedImg } = await this.cache.get(src);
        img.src = loadedImg.src; // 使用已載入的快取
        img.classList.add('loaded');
      } catch {
        img.classList.add('error');
      }
    }
  }

  disconnect() { this.observer.disconnect(); }
}

// 使用
const loader = new LazyImageLoader();
document.querySelectorAll('img[data-src]').forEach(img => loader.observe(img));

CSS 配合:淡入動畫與佔位


img[data-src] {
  opacity: 0;
  transition: opacity 0.4s ease;
  background: #f0f0f0; /* 佔位色 */
  min-height: 100px; /* 防止佈局塌陷 */
}
img.loaded { opacity: 1; }
img.error { opacity: 0.5; filter: grayscale(1); }

效能與快取策略建議

策略適用場景實作要點
Service Worker 預快取PWA、靜態資源固定install 事件中 cache.addAll(urls)
HTTP/2 多路複用大量小圖單域名、啟用 H2,無需域名分片
WebP/AVIF + picture 標籤現代瀏覽器<picture><source type="image/avif" srcset="..."><img>
Blur-up / LQIP大圖首屏內聯 Base64 縮圖做佔位,載入完成後替換
CDN 圖片即時轉檔動態尺寸需求如 Cloudinary、Imgix、自建 thumbor

結語

圖片預載入不只是「先下載」,而是包含並發控制、進度回饋、錯誤重試、快取複用、懶載入協同的完整工程體系。將核心邏輯封裝為 preloadImage / preloadImages / LazyImageLoader 三層 API,即可覆蓋從簡單 Hero 圖到複雜圖庫的所有場景。建議搭配現代圖片格式、CDN 轉檔與 Service Worker,構建極致的圖片載入體驗。

copyright © 萬盛學電腦網 all rights reserved