README

JavaScript就像在问：“你的图片加载好了吗？”

imagesloaded.desandro.com

检测图片是否加载完毕。

安装

下载

imagesloaded.pkgd.min.js 压缩版
imagesloaded.pkgd.js 未压缩版

CDN

<script src="https://npmcdn.com/imagesloaded@4.1/imagesloaded.pkgd.min.js"></script>
<!-- or -->
<script src="https://npmcdn.com/imagesloaded@4.1/imagesloaded.pkgd.js"></script>

包管理器

通过 npm 安装: npm install imagesloaded

通过 Bower 安装: bower install imagesloaded --save

jQuery

您可以将 imagesLoaded 作为 jQuery 插件使用。

$('#container').imagesLoaded( function() {
  // images have loaded
});

// options
$('#container').imagesLoaded( {
  // options...
  },
  function() {
    // images have loaded
  }
);

.imagesLoaded() 返回一个 jQuery 延迟对象。这允许您使用 .always()、.done()、.fail() 和 .progress()。

$('#container').imagesLoaded()
  .always( function( instance ) {
    console.log('all images loaded');
  })
  .done( function( instance ) {
    console.log('all images successfully loaded');
  })
  .fail( function() {
    console.log('all images loaded, at least one is broken');
  })
  .progress( function( instance, image ) {
    var result = image.isLoaded ? 'loaded' : 'broken';
    console.log( 'image is ' + result + ' for ' + image.img.src );
  });

原生 JavaScript

您可以使用 imagesLoaded 和原生 JavaScript。

imagesLoaded( elem, callback )
// options
imagesLoaded( elem, options, callback )
// you can use `new` if you like
new imagesLoaded( elem, callback )

elem 元素、NodeList、数组或选择器字符串
options 对象
callback 函数 - 所有图片加载完毕后触发的函数

使用回调函数与绑定到 always 事件相同（见下文）。

// element
imagesLoaded( document.querySelector('#container'), function( instance ) {
  console.log('all images are loaded');
});
// selector string
imagesLoaded( '#container', function() {...});
// multiple elements
var posts = document.querySelectorAll('.post');
imagesLoaded( posts, function() {...});

使用原生 JavaScript 的 .on()、.off() 和 .once() 方法绑定事件。

var imgLoad = imagesLoaded( elem );
function onAlways( instance ) {
  console.log('all images are loaded');
}
// bind with .on()
imgLoad.on( 'always', onAlways );
// unbind with .off()
imgLoad.off( 'always', onAlways );

背景

除了 <img> 之外，还可以检测背景图片是否加载。

设置 { background: true } 以检测元素背景图片是否加载。

// jQuery
$('#container').imagesLoaded( { background: true }, function() {
  console.log('#container background image loaded');
});

// vanilla JS
imagesLoaded( '#container', { background: true }, function() {
  console.log('#container background image loaded');
});

在 CodePen 上查看 jQuery 示例或原生 JavaScript 示例。

设置选择器字符串，例如 { background: '.item' } 以检测子元素的背景图片是否加载。

// jQuery
$('#container').imagesLoaded( { background: '.item' }, function() {
  console.log('all .item background images loaded');
});

// vanilla JS
imagesLoaded( '#container', { background: '.item' }, function() {
  console.log('all .item background images loaded');
});

在 CodePen 上查看 jQuery 示例或原生 JavaScript 示例。

事件

always

// jQuery
$('#container').imagesLoaded().always( function( instance ) {
  console.log('ALWAYS - all images have been loaded');
});

// vanilla JS
imgLoad.on( 'always', function( instance ) {
  console.log('ALWAYS - all images have been loaded');
});

在所有图片已加载或确认损坏后触发。

instance imagesLoaded - imagesLoaded 实例

done

// jQuery
$('#container').imagesLoaded().done( function( instance ) {
  console.log('DONE  - all images have been successfully loaded');
});

// vanilla JS
imgLoad.on( 'done', function( instance ) {
  console.log('DONE  - all images have been successfully loaded');
});

在所有图片成功加载且没有损坏的图片后触发。

fail

$('#container').imagesLoaded().fail( function( instance ) {
  console.log('FAIL - all images loaded, at least one is broken');
});

// vanilla JS
imgLoad.on( 'fail', function( instance ) {
  console.log('FAIL - all images loaded, at least one is broken');
});

在所有图片加载完毕且至少有一张图片损坏后触发。

progress

imgLoad.on( 'progress', function( instance, image ) {
  var result = image.isLoaded ? 'loaded' : 'broken';
  console.log( 'image is ' + result + ' for ' + image.img.src );
});

在每张图片加载后触发。

instance imagesLoaded - imagesLoaded 实例
image LoadingImage - 已加载图片的 LoadingImage 实例

属性

LoadingImage.img

Image - The img 元素

LoadingImage.isLoaded

布尔值 - 当图片成功加载时为 true

imagesLoaded.images

每个检测到的图片的 LoadingImage 实例数组

var imgLoad = imagesLoaded('#container');
imgLoad.on( 'always', function() {
  console.log( imgLoad.images.length + ' images loaded' );
  // detect which image is broken
  for ( var i = 0, len = imgLoad.images.length; i < len; i++ ) {
    var image = imgLoad.images[i];
    var result = image.isLoaded ? 'loaded' : 'broken';
    console.log( 'image is ' + result + ' for ' + image.img.src );
  }
});

Browserify

imagesLoaded 与 Browserify 兼容。

npm install imagesloaded --save

var imagesLoaded = require('imagesloaded');

imagesLoaded( elem, function() {...} );

使用 .makeJQueryPlugin 来使用 .imagesLoaded() jQuery 插件。

var $ = require('jquery');
var imagesLoaded = require('imagesloaded');

// provide jQuery argument
imagesLoaded.makeJQueryPlugin( $ );
// now use .imagesLoaded() jQuery plugin
$('#container').imagesLoaded( function() {...});

Webpack

使用 npm 安装 imagesLoaded 和 imports-loader。

npm install imagesloaded imports-loader

在您的配置文件 webpack.config.js 中，使用导入加载器禁用 define 并设置 imagesloaded 的 window。

module.exports = {
  module: {
    loaders: [
      {
        test: /imagesloaded|ev\-emitter/,
        loader: 'imports?define=>false&this=>window'
      }
    ]
  }
};

（由于 Webpack 加载依赖项的问题，需要此修改。在 GitHub 上为该问题 +1 以帮助解决这个问题：+1 this issue on GitHub。）

然后，您可以使用 require('imagesloaded')。

// main.js
var imagesLoaded = require('imagesLoaded');

imagesLoaded( '#container', function() {
  // images have loaded
});

使用 .makeJQueryPlugin 创建 .imagesLoaded() jQuery 插件。

// main.js
var imagesLoaded = require('imagesLoaded');
var jQuery = require('jquery');

// provide jQuery argument
imagesLoaded.makeJQueryPlugin( $ );
// now use .imagesLoaded() jQuery plugin
$('#container').imagesLoaded( function() {...});

运行 webpack。

webpack main.js bundle.js

RequireJS

imagesLoaded 与 RequireJS 兼容。

您可以引入 imagesloaded.pkgd.js。

requirejs( [
  'path/to/imagesloaded.pkgd.js',
], function( imagesLoaded ) {
  imagesLoaded( '#container', function() { ... });
});