Universal Image Loader库使用方法

UIL aims to provide a powerful, flexible and highly customizable instrument for image loading, caching and displaying. It provides a lot of configuration options and good control over the image loading and caching process.

Project News

Upcoming changes in new UIL version (1.9.4+)

Memory Cache redesign
Video file thumbnail support via "file:///sdcard/video.mp4"
New API: DisplayImageOptions.targetSize(ImageSize)
HTTP cache support
Consider BitmapFactory.Options.inBitmap
Time-to-live option for files in LruDiskCache

Features

Multithread image loading (async or sync)
Wide customization of ImageLoader's configuration (thread executors, downloader, decoder, memory and disk cache, display image options, etc.)
Many customization options for every display image call (stub images, caching switch, decoding options, Bitmap processing and displaying, etc.)
Image caching in memory and/or on disk (device's file system or SD card)
Listening loading process (including downloading progress)

Android 2.0+ support

Downloads

universal-image-loader-1.9.3.jar
universal-image-loader-1.9.3-sources.jar
universal-image-loader-1.9.3-javadoc.jar
universal-image-loader-1.9.3-with-sources.jar

Documentation | Useful Info | User Support | Changelog

Quick Setup

1. Include library

Manual:

Download JAR
Put the JAR in the libs subfolder of your Android project

Maven dependency:

<dependency>    <groupId>com.nostra13.universalimageloadergroupId>    <artifactId>universal-image-loaderartifactId>    <version>1.9.3version>dependency>

Gradle dependency:

compile 'com.nostra13.universalimageloader:universal-image-loader:1.9.3'

2. Android Manifest

<manifest>        <uses-permission android:name="android.permission.INTERNET" />        <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />    ...manifest>

3. Application or Activity class (before the first usage of ImageLoader)

public class MyActivity extends Activity {    @Override    public void onCreate() {        super.onCreate();        // Create global configuration and initialize ImageLoader with this config        ImageLoaderConfiguration config = new ImageLoaderConfiguration.Builder(this)            ...            .build();        ImageLoader.getInstance().init(config);        ...    }}

Configuration and Display Options

ImageLoader Configuration (ImageLoaderConfiguration) is global for application.
Display Options (DisplayImageOptions) are local for every display task (ImageLoader.displayImage(...)).

Configuration

All options in Configuration builder are optional. Use only those you really want to customize.
See default values for config options in Java docs for every option.

// DON'T COPY THIS CODE TO YOUR PROJECT! This is just example of ALL options using.// See the sample project how to use ImageLoader correctly.File cacheDir = StorageUtils.getCacheDirectory(context);ImageLoaderConfiguration config = new ImageLoaderConfiguration.Builder(context)        .memoryCacheExtraOptions(480, 800) // default = device screen dimensions        .diskCacheExtraOptions(480, 800, null)        .taskExecutor(...)        .taskExecutorForCachedImages(...)        .threadPoolSize(3) // default        .threadPriority(Thread.NORM_PRIORITY - 2) // default        .tasksProcessingOrder(QueueProcessingType.FIFO) // default        .denyCacheImageMultipleSizesInMemory()        .memoryCache(new LruMemoryCache(2 * 1024 * 1024))        .memoryCacheSize(2 * 1024 * 1024)        .memoryCacheSizePercentage(13) // default        .diskCache(new UnlimitedDiscCache(cacheDir)) // default        .diskCacheSize(50 * 1024 * 1024)        .diskCacheFileCount(100)        .diskCacheFileNameGenerator(new HashCodeFileNameGenerator()) // default        .imageDownloader(new BaseImageDownloader(context)) // default        .imageDecoder(new BaseImageDecoder()) // default        .defaultDisplayImageOptions(DisplayImageOptions.createSimple()) // default        .writeDebugLogs()        .build();

Display Options

Display Options can be applied to every display task (ImageLoader.displayImage(...) call).

Note: If Display Options wasn't passed to ImageLoader.displayImage(...)method then default Display Options from configuration (ImageLoaderConfiguration.defaultDisplayImageOptions(...)) will be used.

// DON'T COPY THIS CODE TO YOUR PROJECT! This is just example of ALL options using.// See the sample project how to use ImageLoader correctly.DisplayImageOptions options = new DisplayImageOptions.Builder()        .showImageOnLoading(R.drawable.ic_stub) // resource or drawable        .showImageForEmptyUri(R.drawable.ic_empty) // resource or drawable        .showImageOnFail(R.drawable.ic_error) // resource or drawable        .resetViewBeforeLoading(false)  // default        .delayBeforeLoading(1000)        .cacheInMemory(false) // default        .cacheOnDisk(false) // default        .preProcessor(...)        .postProcessor(...)        .extraForDownloader(...)        .considerExifParams(false) // default        .imageScaleType(ImageScaleType.IN_SAMPLE_POWER_OF_2) // default        .bitmapConfig(Bitmap.Config.ARGB_8888) // default        .decodingOptions(...)        .displayer(new SimpleBitmapDisplayer()) // default        .handler(new Handler()) // default        .build();

Usage

Acceptable URIs examples

"http://site.com/image.png" // from Web"file:///mnt/sdcard/image.png" // from SD card"file:///mnt/sdcard/video.mp4" // from SD card (video thumbnail)"content://media/external/images/media/13" // from content provider"content://media/external/video/media/13" // from content provider (video thumbnail)"assets://image.png" // from assets"drawable://" + R.drawable.img // from drawables (non-9patch images)

NOTE: Use drawable:// only if you really need it! Always consider the native way to load drawables - ImageView.setImageResource(...) instead of using of ImageLoader.

Simple

// Load image, decode it to Bitmap and display Bitmap in ImageView (or any other view //  which implements ImageAware interface)imageLoader.displayImage(imageUri, imageView);

// Load image, decode it to Bitmap and return Bitmap to callbackimageLoader.loadImage(imageUri, new SimpleImageLoadingListener() {    @Override    public void onLoadingComplete(String imageUri, View view, Bitmap loadedImage) {        // Do whatever you want with Bitmap    }});

// Load image, decode it to Bitmap and return Bitmap synchronouslyBitmap bmp = imageLoader.loadImageSync(imageUri);

Complete

// Load image, decode it to Bitmap and display Bitmap in ImageView (or any other view //  which implements ImageAware interface)imageLoader.displayImage(imageUri, imageView, options, new ImageLoadingListener() {    @Override    public void onLoadingStarted(String imageUri, View view) {        ...    }    @Override    public void onLoadingFailed(String imageUri, View view, FailReason failReason) {        ...    }    @Override    public void onLoadingComplete(String imageUri, View view, Bitmap loadedImage) {        ...    }    @Override    public void onLoadingCancelled(String imageUri, View view) {        ...    }}, new ImageLoadingProgressListener() {    @Override    public void onProgressUpdate(String imageUri, View view, int current, int total) {        ...    }});

// Load image, decode it to Bitmap and return Bitmap to callbackImageSize targetSize = new ImageSize(80, 50); // result Bitmap will be fit to this sizeimageLoader.loadImage(imageUri, targetSize, options, new SimpleImageLoadingListener() {    @Override    public void onLoadingComplete(String imageUri, View view, Bitmap loadedImage) {        // Do whatever you want with Bitmap    }});

// Load image, decode it to Bitmap and return Bitmap synchronouslyImageSize targetSize = new ImageSize(80, 50); // result Bitmap will be fit to this sizeBitmap bmp = imageLoader.loadImageSync(imageUri, targetSize, options);