Android-Universal-Image-Loader三大组件DisplayImageOptions、ImageLoader、ImageLoaderConfiguration详解

一、介绍

二、具体使用

1 public class BaseActivity extends Activity {
 2     ImageLoader imageLoader;
 3     @Override
 4     protected void onCreate(Bundle savedInstanceState) {
 5           // Create global configuration and initialize ImageLoader with this configuration
 6         ImageLoaderConfiguration config = new ImageLoaderConfiguration.Builder(getApplicationContext())
 7             .build();
 8         ImageLoader.getInstance().init(config);
 9         super.onCreate(savedInstanceState);
10     }
11 }

1 public class MainActivity extends BaseActivity {
  2 
  3     @Override
  4     protected void onCreate(Bundle savedInstanceState) {
  5         super.onCreate(savedInstanceState);
  6         setContentView(R.layout.activity_main);
  7   
  8         ImageLoader imageLoader = ImageLoader.getInstance();
  9 
 10         GridView gridView = (GridView) this.findViewById(R.id.grdvImageWall);
 11         gridView.setAdapter(new PhotoWallAdapter(Constants.IMAGES));
 12     }
 13 
 14     static class ViewHolder {
 15         ImageView imageView;
 16         ProgressBar progressBar;
 17     }
 18 
 19     public class PhotoWallAdapter extends BaseAdapter {
 20         String[] imageUrls;
 21         ImageLoader imageLoad;
 22         DisplayImageOptions options;
 23         LinearLayout gridViewItem;
 24 
 25         public PhotoWallAdapter(String[] imageUrls) {
 26             assert imageUrls != null;
 27             this.imageUrls = imageUrls;
 28 
 29             options = new DisplayImageOptions.Builder()
 30                     .showImageOnLoading(R.drawable.ic_stub) // resource or
 31                                                             // drawable
 32                     .showImageForEmptyUri(R.drawable.ic_empty) // resource or
 33                                                                 // drawable
 34                     .showImageOnFail(R.drawable.ic_error) // resource or
 35                                                             // drawable
 36                     .resetViewBeforeLoading(false) // default
 37                     .delayBeforeLoading(1000).cacheInMemory(false) // default
 38                     .cacheOnDisk(false) // default
 39                     .considerExifParams(false) // default
 40                     .imageScaleType(ImageScaleType.IN_SAMPLE_POWER_OF_2) // default
 41                     .bitmapConfig(Bitmap.Config.ARGB_8888) // default
 42                     .displayer(new SimpleBitmapDisplayer()) // default
 43                     .handler(new Handler()) // default
 44                     .build();
 45             this.imageLoad = ImageLoader.getInstance();
 46 
 47         }
 48 
 49         @Override
 50         public int getCount() {
 51             return this.imageUrls.length;
 52         }
 53 
 54         @Override
 55         public Object getItem(int position) {
 56             if (position <= 0 || position >= this.imageUrls.length) {
 57                 throw new IllegalArgumentException(
 58                         "position<=0||position>=this.imageUrls.length");
 59             }
 60             return this.imageUrls[position];
 61         }
 62 
 63         @Override
 64         public long getItemId(int position) {
 65             return position;
 66         }
 67 
 68         @Override
 69         public View getView(int position, View convertView, ViewGroup parent) {
 70             // 判断这个image是否已经在缓存当中，如果没有就下载
 71             final ViewHolder holder;
 72             if (convertView == null) {
 73                 holder = new ViewHolder();
 74                 gridViewItem = (LinearLayout) getLayoutInflater().inflate(
 75                         R.layout.image_wall_item, null);
 76                 holder.imageView = (ImageView) gridViewItem
 77                         .findViewById(R.id.item_image);
 78                 holder.progressBar = (ProgressBar) gridViewItem
 79                         .findViewById(R.id.item_process);
 80                 gridViewItem.setTag(holder);
 81                 convertView = gridViewItem;
 82             } else {
 83                 holder = (ViewHolder) gridViewItem.getTag();
 84             }
 85             this.imageLoad.displayImage(this.imageUrls[position],
 86                     holder.imageView, options,
 87                     new SimpleImageLoadingListener() {
 88 
 89                         @Override
 90                         public void onLoadingStarted(String imageUri, View view) {
 91                             holder.progressBar.setProgress(0);
 92                             holder.progressBar.setVisibility(View.VISIBLE);
 93                         }
 94 
 95                         @Override
 96                         public void onLoadingFailed(String imageUri, View view,
 97                                 FailReason failReason) {
 98                             holder.progressBar.setVisibility(View.GONE);
 99                         }
100 
101                         @Override
102                         public void onLoadingComplete(String imageUri,
103                                 View view, Bitmap loadedImage) {
104                             holder.progressBar.setVisibility(View.GONE);
105                         }
106 
107                     }, new ImageLoadingProgressListener() {
108 
109                         @Override
110                         public void onProgressUpdate(String imageUri,
111                                 View view, int current, int total) {
112                             holder.progressBar.setProgress(Math.round(100.0f
113                                     * current / total));
114                         }
115                     }); // 通过URL判断图片是否已经下载
116             return convertView;
117         }
118 
119     }
120 }

三者的关系

ImageLoaderConfiguration

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 - 1) // 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

ImageLoader.displayImage(...)

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

1 public final class DisplayImageOptions {
  2 
  3     private final int imageResOnLoading;
  4     private final int imageResForEmptyUri;
  5     private final int imageResOnFail;
  6     private final Drawable imageOnLoading;
  7     private final Drawable imageForEmptyUri;
  8     private final Drawable imageOnFail;
  9     private final boolean resetViewBeforeLoading;
 10     private final boolean cacheInMemory;
 11     private final boolean cacheOnDisk;
 12     private final ImageScaleType imageScaleType;
 13     private final Options decodingOptions;
 14     private final int delayBeforeLoading;
 15     private final boolean considerExifParams;
 16     private final Object extraForDownloader;
 17     private final BitmapProcessor preProcessor;
 18     private final BitmapProcessor postProcessor;
 19     private final BitmapDisplayer displayer;
 20     private final Handler handler;
 21     private final boolean isSyncLoading;
 22 
 23     private DisplayImageOptions(Builder builder) {
 24         imageResOnLoading = builder.imageResOnLoading;
 25         imageResForEmptyUri = builder.imageResForEmptyUri;
 26         imageResOnFail = builder.imageResOnFail;
 27         imageOnLoading = builder.imageOnLoading;
 28         imageForEmptyUri = builder.imageForEmptyUri;
 29         imageOnFail = builder.imageOnFail;
 30         resetViewBeforeLoading = builder.resetViewBeforeLoading;
 31         cacheInMemory = builder.cacheInMemory;
 32         cacheOnDisk = builder.cacheOnDisk;
 33         imageScaleType = builder.imageScaleType;
 34         decodingOptions = builder.decodingOptions;
 35         delayBeforeLoading = builder.delayBeforeLoading;
 36         considerExifParams = builder.considerExifParams;
 37         extraForDownloader = builder.extraForDownloader;
 38         preProcessor = builder.preProcessor;
 39         postProcessor = builder.postProcessor;
 40         displayer = builder.displayer;
 41         handler = builder.handler;
 42         isSyncLoading = builder.isSyncLoading;
 43     }
 44 
 45     public boolean shouldShowImageOnLoading() {
 46         return imageOnLoading != null || imageResOnLoading != 0;
 47     }
 48 
 49     public boolean shouldShowImageForEmptyUri() {
 50         return imageForEmptyUri != null || imageResForEmptyUri != 0;
 51     }
 52 
 53     public boolean shouldShowImageOnFail() {
 54         return imageOnFail != null || imageResOnFail != 0;
 55     }
 56 
 57     public boolean shouldPreProcess() {
 58         return preProcessor != null;
 59     }
 60 
 61     public boolean shouldPostProcess() {
 62         return postProcessor != null;
 63     }
 64 
 65     public boolean shouldDelayBeforeLoading() {
 66         return delayBeforeLoading > 0;
 67     }
 68 
 69     public Drawable getImageOnLoading(Resources res) {
 70         return imageResOnLoading != 0 ? res.getDrawable(imageResOnLoading) : imageOnLoading;
 71     }
 72 
 73     public Drawable getImageForEmptyUri(Resources res) {
 74         return imageResForEmptyUri != 0 ? res.getDrawable(imageResForEmptyUri) : imageForEmptyUri;
 75     }
 76 
 77     public Drawable getImageOnFail(Resources res) {
 78         return imageResOnFail != 0 ? res.getDrawable(imageResOnFail) : imageOnFail;
 79     }
 80 
 81     public boolean isResetViewBeforeLoading() {
 82         return resetViewBeforeLoading;
 83     }
 84 
 85     public boolean isCacheInMemory() {
 86         return cacheInMemory;
 87     }
 88 
 89     public boolean isCacheOnDisk() {
 90         return cacheOnDisk;
 91     }
 92 
 93     public ImageScaleType getImageScaleType() {
 94         return imageScaleType;
 95     }
 96 
 97     public Options getDecodingOptions() {
 98         return decodingOptions;
 99     }
100 
101     public int getDelayBeforeLoading() {
102         return delayBeforeLoading;
103     }
104 
105     public boolean isConsiderExifParams() {
106         return considerExifParams;
107     }
108 
109     public Object getExtraForDownloader() {
110         return extraForDownloader;
111     }
112 
113     public BitmapProcessor getPreProcessor() {
114         return preProcessor;
115     }
116 
117     public BitmapProcessor getPostProcessor() {
118         return postProcessor;
119     }
120 
121     public BitmapDisplayer getDisplayer() {
122         return displayer;
123     }
124 
125     public Handler getHandler() {
126         return handler;
127     }
128 
129     boolean isSyncLoading() {
130         return isSyncLoading;
131     }
132 
133     /**
134      * Builder for {@link DisplayImageOptions}
135      *
136      * @author Sergey Tarasevich (nostra13[at]gmail[dot]com)
137      */
138     public static class Builder {
139         private int imageResOnLoading = 0;
140         private int imageResForEmptyUri = 0;
141         private int imageResOnFail = 0;
142         private Drawable imageOnLoading = null;
143         private Drawable imageForEmptyUri = null;
144         private Drawable imageOnFail = null;
145         private boolean resetViewBeforeLoading = false;
146         private boolean cacheInMemory = false;
147         private boolean cacheOnDisk = false;
148         private ImageScaleType imageScaleType = ImageScaleType.IN_SAMPLE_POWER_OF_2;
149         private Options decodingOptions = new Options();
150         private int delayBeforeLoading = 0;
151         private boolean considerExifParams = false;
152         private Object extraForDownloader = null;
153         private BitmapProcessor preProcessor = null;
154         private BitmapProcessor postProcessor = null;
155         private BitmapDisplayer displayer = DefaultConfigurationFactory.createBitmapDisplayer();
156         private Handler handler = null;
157         private boolean isSyncLoading = false;
158 
159         public Builder() {
160             decodingOptions.inPurgeable = true;
161             decodingOptions.inInputShareable = true;
162         }
163 
164         /**
165          * Stub image will be displayed in {@link com.nostra13.universalimageloader.core.imageaware.ImageAware
166          * image aware view} during image loading
167          *
168          * @param imageRes Stub image resource
169          * @deprecated Use {@link #showImageOnLoading(int)} instead
170          */
171         @Deprecated
172         public Builder showStubImage(int imageRes) {
173             imageResOnLoading = imageRes;
174             return this;
175         }
176 
177         /**
178          * Incoming image will be displayed in {@link com.nostra13.universalimageloader.core.imageaware.ImageAware
179          * image aware view} during image loading
180          *
181          * @param imageRes Image resource
182          */
183         public Builder showImageOnLoading(int imageRes) {
184             imageResOnLoading = imageRes;
185             return this;
186         }
187 
188         /**
189          * Incoming drawable will be displayed in {@link com.nostra13.universalimageloader.core.imageaware.ImageAware
190          * image aware view} during image loading.
191          * This option will be ignored if {@link DisplayImageOptions.Builder#showImageOnLoading(int)} is set.
192          */
193         public Builder showImageOnLoading(Drawable drawable) {
194             imageOnLoading = drawable;
195             return this;
196         }
197 
198         /**
199          * Incoming image will be displayed in {@link com.nostra13.universalimageloader.core.imageaware.ImageAware
200          * image aware view} if empty URI (null or empty
201          * string) will be passed to <b>ImageLoader.displayImage(...)</b> method.
202          *
203          * @param imageRes Image resource
204          */
205         public Builder showImageForEmptyUri(int imageRes) {
206             imageResForEmptyUri = imageRes;
207             return this;
208         }
209 
210         /**
211          * Incoming drawable will be displayed in {@link com.nostra13.universalimageloader.core.imageaware.ImageAware
212          * image aware view} if empty URI (null or empty
213          * string) will be passed to <b>ImageLoader.displayImage(...)</b> method.
214          * This option will be ignored if {@link DisplayImageOptions.Builder#showImageForEmptyUri(int)} is set.
215          */
216         public Builder showImageForEmptyUri(Drawable drawable) {
217             imageForEmptyUri = drawable;
218             return this;
219         }
220 
221         /**
222          * Incoming image will be displayed in {@link com.nostra13.universalimageloader.core.imageaware.ImageAware
223          * image aware view} if some error occurs during
224          * requested image loading/decoding.
225          *
226          * @param imageRes Image resource
227          */
228         public Builder showImageOnFail(int imageRes) {
229             imageResOnFail = imageRes;
230             return this;
231         }
232 
233         /**
234          * Incoming drawable will be displayed in {@link com.nostra13.universalimageloader.core.imageaware.ImageAware
235          * image aware view} if some error occurs during
236          * requested image loading/decoding.
237          * This option will be ignored if {@link DisplayImageOptions.Builder#showImageOnFail(int)} is set.
238          */
239         public Builder showImageOnFail(Drawable drawable) {
240             imageOnFail = drawable;
241             return this;
242         }
243 
244         /**
245          * {@link com.nostra13.universalimageloader.core.imageaware.ImageAware
246          * image aware view} will be reset (set <b>null</b>) before image loading start
247          *
248          * @deprecated Use {@link #resetViewBeforeLoading(boolean) resetViewBeforeLoading(true)} instead
249          */
250         public Builder resetViewBeforeLoading() {
251             resetViewBeforeLoading = true;
252             return this;
253         }
254 
255         /**
256          * Sets whether {@link com.nostra13.universalimageloader.core.imageaware.ImageAware
257          * image aware view} will be reset (set <b>null</b>) before image loading start
258          */
259         public Builder resetViewBeforeLoading(boolean resetViewBeforeLoading) {
260             this.resetViewBeforeLoading = resetViewBeforeLoading;
261             return this;
262         }
263 
264         /**
265          * Loaded image will be cached in memory
266          *
267          * @deprecated Use {@link #cacheInMemory(boolean) cacheInMemory(true)} instead
268          */
269         @Deprecated
270         public Builder cacheInMemory() {
271             cacheInMemory = true;
272             return this;
273         }
274 
275         /** Sets whether loaded image will be cached in memory */
276         public Builder cacheInMemory(boolean cacheInMemory) {
277             this.cacheInMemory = cacheInMemory;
278             return this;
279         }
280 
281         /**
282          * Loaded image will be cached on disk
283          *
284          * @deprecated Use {@link #cacheOnDisk(boolean) cacheOnDisk(true)} instead
285          */
286         @Deprecated
287         public Builder cacheOnDisc() {
288             return cacheOnDisk(true);
289         }
290 
291         /**
292          * Sets whether loaded image will be cached on disk
293          *
294          * @deprecated Use {@link #cacheOnDisk(boolean)} instead
295          */
296         @Deprecated
297         public Builder cacheOnDisc(boolean cacheOnDisk) {
298             return cacheOnDisk(cacheOnDisk);
299         }
300 
301         /** Sets whether loaded image will be cached on disk */
302         public Builder cacheOnDisk(boolean cacheOnDisk) {
303             this.cacheOnDisk = cacheOnDisk;
304             return this;
305         }
306 
307         /**
308          * Sets {@linkplain ImageScaleType scale type} for decoding image. This parameter is used while define scale
309          * size for decoding image to Bitmap. Default value - {@link ImageScaleType#IN_SAMPLE_POWER_OF_2}
310          */
311         public Builder imageScaleType(ImageScaleType imageScaleType) {
312             this.imageScaleType = imageScaleType;
313             return this;
314         }
315 
316         /** Sets {@link Bitmap.Config bitmap config} for image decoding. Default value - {@link Bitmap.Config#ARGB_8888} */
317         public Builder bitmapConfig(Bitmap.Config bitmapConfig) {
318             if (bitmapConfig == null) throw new IllegalArgumentException("bitmapConfig can't be null");
319             decodingOptions.inPreferredConfig = bitmapConfig;
320             return this;
321         }
322 
323         /**
324          * Sets options for image decoding.<br />
325          * <b>NOTE:</b> {@link Options#inSampleSize} of incoming options will <b>NOT</b> be considered. Library
326          * calculate the most appropriate sample size itself according yo {@link #imageScaleType(ImageScaleType)}
327          * options.<br />
328          * <b>NOTE:</b> This option overlaps {@link #bitmapConfig(android.graphics.Bitmap.Config) bitmapConfig()}
329          * option.
330          */
331         public Builder decodingOptions(Options decodingOptions) {
332             if (decodingOptions == null) throw new IllegalArgumentException("decodingOptions can't be null");
333             this.decodingOptions = decodingOptions;
334             return this;
335         }
336 
337         /** Sets delay time before starting loading task. Default - no delay. */
338         public Builder delayBeforeLoading(int delayInMillis) {
339             this.delayBeforeLoading = delayInMillis;
340             return this;
341         }
342 
343         /** Sets auxiliary object which will be passed to {@link ImageDownloader#getStream(String, Object)} */
344         public Builder extraForDownloader(Object extra) {
345             this.extraForDownloader = extra;
346             return this;
347         }
348 
349         /** Sets whether ImageLoader will consider EXIF parameters of JPEG image (rotate, flip) */
350         public Builder considerExifParams(boolean considerExifParams) {
351             this.considerExifParams = considerExifParams;
352             return this;
353         }
354 
355         /**
356          * Sets bitmap processor which will be process bitmaps before they will be cached in memory. So memory cache
357          * will contain bitmap processed by incoming preProcessor.<br />
358          * Image will be pre-processed even if caching in memory is disabled.
359          */
360         public Builder preProcessor(BitmapProcessor preProcessor) {
361             this.preProcessor = preProcessor;
362             return this;
363         }
364 
365         /**
366          * Sets bitmap processor which will be process bitmaps before they will be displayed in
367          * {@link com.nostra13.universalimageloader.core.imageaware.ImageAware image aware view} but
368          * after they'll have been saved in memory cache.
369          */
370         public Builder postProcessor(BitmapProcessor postProcessor) {
371             this.postProcessor = postProcessor;
372             return this;
373         }
374 
375         /**
376          * Sets custom {@link BitmapDisplayer displayer} for image loading task. Default value -
377          * {@link DefaultConfigurationFactory#createBitmapDisplayer()}
378          */
379         public Builder displayer(BitmapDisplayer displayer) {
380             if (displayer == null) throw new IllegalArgumentException("displayer can't be null");
381             this.displayer = displayer;
382             return this;
383         }
384 
385         Builder syncLoading(boolean isSyncLoading) {
386             this.isSyncLoading = isSyncLoading;
387             return this;
388         }
389 
390         /**
391          * Sets custom {@linkplain Handler handler} for displaying images and firing {@linkplain ImageLoadingListener
392          * listener} events.
393          */
394         public Builder handler(Handler handler) {
395             this.handler = handler;
396             return this;
397         }
398 
399         /** Sets all options equal to incoming options */
400         public Builder cloneFrom(DisplayImageOptions options) {
401             imageResOnLoading = options.imageResOnLoading;
402             imageResForEmptyUri = options.imageResForEmptyUri;
403             imageResOnFail = options.imageResOnFail;
404             imageOnLoading = options.imageOnLoading;
405             imageForEmptyUri = options.imageForEmptyUri;
406             imageOnFail = options.imageOnFail;
407             resetViewBeforeLoading = options.resetViewBeforeLoading;
408             cacheInMemory = options.cacheInMemory;
409             cacheOnDisk = options.cacheOnDisk;
410             imageScaleType = options.imageScaleType;
411             decodingOptions = options.decodingOptions;
412             delayBeforeLoading = options.delayBeforeLoading;
413             considerExifParams = options.considerExifParams;
414             extraForDownloader = options.extraForDownloader;
415             preProcessor = options.preProcessor;
416             postProcessor = options.postProcessor;
417             displayer = options.displayer;
418             handler = options.handler;
419             isSyncLoading = options.isSyncLoading;
420             return this;
421         }
422 
423         /** Builds configured {@link DisplayImageOptions} object */
424         public DisplayImageOptions build() {
425             return new DisplayImageOptions(this);
426         }
427     }
428 
429     /**
430      * Creates options appropriate for single displaying:
431      * <ul>
432      * <li>View will <b>not</b> be reset before loading</li>
433      * <li>Loaded image will <b>not</b> be cached in memory</li>
434      * <li>Loaded image will <b>not</b> be cached on disk</li>
435      * <li>{@link ImageScaleType#IN_SAMPLE_POWER_OF_2} decoding type will be used</li>
436      * <li>{@link Bitmap.Config#ARGB_8888} bitmap config will be used for image decoding</li>
437      * <li>{@link SimpleBitmapDisplayer} will be used for image displaying</li>
438      * </ul>
439      * <p/>
440      * These option are appropriate for simple single-use image (from drawables or from Internet) displaying.
441      */
442     public static DisplayImageOptions createSimple() {
443         return new Builder().build();
444     }
445 }