[翻譯] AsyncImageView 異步下載圖片

AsyncImageView 

https://github.com/nicklockwood/AsyncImageView

AsyncImageView is a simple extension of UIImageView for loading and displaying images asynchronously on iOS so that they do not lock up the UI.

AsyncImageView是關於UIImageView的擴展，用來異步加載和顯示圖片防止阻塞UI。

Purpose（目的）

AsyncImageView includes both a simple category on UIImageView for loading and displaying images asynchronously on iOS so that they do not lock up the UI, and a UIImageView subclass for more advanced features. AsyncImageView works with URLs so it can be used with either local or remote files.

Loaded/downloaded images are cached in memory and are automatically cleaned up in the event of a memory warning. The AsyncImageView operates independently of the UIImage cache, but by default any images located in the root of the application bundle will be stored in the UIImage cache instead, avoiding any duplication of cached images.

The library can also be used to load and cache images independently of a UIImageView as it provides direct access to the underlying loading and caching classes.

AsyncImageView包含了兩種類型，一種是UIImageView的類目，用來異步加載以及顯示圖片的。另外一種是UIImageView的子類，含有更多的一些特性。AsyncImageView 經過URL來工做，因此，既能夠是本地的圖片，也能夠是網絡上的圖片。加載和下載圖片是緩存在內存的，因此當出現內存警告時會自動刪除內存中的圖片。AsyncImageView 獨立於UIImage的緩存操做，可是默認的是，任何在bundle中的圖片都被緩存起來了，防止重複的緩存圖片。

Supported OS & SDK Versions（支持OS&SDK的版本）

• Supported build target - iOS 7.1 (Xcode 5.1, Apple LLVM compiler 5.1)
• Earliest supported deployment target - iOS 5.0
• Earliest compatible deployment target - iOS 4.3
• 支持iOS 7.1
• 支持早期的 iOS 5.0
• 兼容更早期的 iOS 4.3

NOTE: 'Supported' means that the library has been tested with this version. 'Compatible' means that the library should work on this iOS version (i.e. it doesn't rely on any unavailable SDK features) but is no longer being tested for compatibility and may require tweaking or bug fixes to run correctly.

注意：支持意味着這個庫已經在那個版本上測試過了。兼容意味着這個庫應該能在那個版本上運行，但之後不會在那個版本上測試，更不會修復那本版本中存在的bug。

ARC Compatibility（ARC狀況）

As of version 1.5, AsyncImageView requires ARC. If you wish to use AsyncImageView in a non-ARC project, just add the -fobjc-arc compiler flag to the AsyncImageView.m file. To do this, go to the Build Phases tab in your target settings, open the Compile Sources group, double-click AsyncImageView.m in the list and type -fobjc-arc into the popover.

If you wish to convert your whole project to ARC, comment out the #error line in AsyncImageView.m, then run the Edit > Refactor > Convert to Objective-C ARC... tool in Xcode and make sure all files that you wish to use ARC for (including AsyncImageView.m) are checked.

從1.5版本開始，AsyncImageView須要開ARC，若是你想將AsyncImageView用在非ARC的項目中，添加編譯標籤 -fobjc-arc 在AsyncImageView.m 文件上。到Bulid Phases 選項卡上找到你的目標文件，打開 Complile Sources 組，雙擊 AsyncImageView.m 文件，鍵入 -fobjc-arc 便可。

若是你想將你整個項目都轉換成ARC，註釋掉含有 #error 的行，而後，運行 Edit>Refactor>Convert to Objective-C ARC... 工具，確保全部要轉換成ARC的文件都檢查過了而沒有遺漏。

Thread Safety（線程安全）

AsyncImageView uses threading internally, but none of the AsyncImageView external interfaces are thread safe, and you should not call any methods or set any properties on any of the AsyncImageView classes except on the main thread.

AsyncImageView 本質上使用了線程，但沒有哪一個AsyncImageView是線程安全的，你不能設置任何的相關線程的屬性，除非在主線程上。

Installation（安裝）

To use the AsyncImageView in an app, just drag the AsyncImageView class files into your project.

僅需將AsyncImageView 文件夾拖入到你的工程項目中便可。

Categories（類目文件）

The basic interface of AsyncImageView is a category that extends UIImageView with the following property:

AsyncImageView 最主要的接口是擴展了一個屬性（擴展了一個屬性？？？？？）

@property (nonatomic, strong) NSURL *imageURL;

Upon setting this property, AsyncImageView will begin loading/downloading the specified image on a background thread. Once the image file has loaded, the UIImageView's image property will be set to the resultant image. If you set this property again while the previous image is still loading then the images will be queued for loading in the order in which they were set.

經過設置這個屬性，AsyncImageView 將會開始在指定的線程中下載加載指定的圖片。當這張圖片加載完成後，這個image的屬性就會被設置成合成的image，若是此時，你再一次設置了這個屬性，那麼，以前加載的圖片還在，然而，新指定的圖片將會進入隊列中按照順序來加載。

This means that you can, for example, set a UIImageView to load a small thumbnail image and then immediately set it to load a larger image and the thumbnail image will still be loaded and set before the larger image loads.

這意味着，你能夠，設置了一張不清晰的圖片，而後你再設置着去加載清晰的圖片，只不過，圖片加載完成後，不清晰的圖片被清晰的圖片覆蓋住了。

If you access this property it will return the most recent image URL set for the UIImageView, which may not be the next one to be loaded if several image URLs have been queued on that image view. If you wish to cancel the previously loading image, use the -cancelLoadingURL:target: method on the AsyncImageLoader class, passing the UIImageView instance as the target (see below).

若是你用了這個屬性設置了不少圖片，他將會返回你設置過的那些圖片的 URL 地址，可是並不必定按照你指定的順序來加載（由於是併發線程嘛），若是你想取消當前加載中的圖片，使用-cancelLoadingURL:target:方法來取消，給UIImageView的一個實例對象使用該方法。

Classes（類）

AsyncImageView includes an AsyncImageView class, which is a subclass of UIImageView. This implements some useful features on top of the UIImageView category, including the automatic display of a loading spinner, and a nice crossfade effect when the image loads.

AsyncImageView also provides an AsyncImageLoader class for advanced users. AsyncImageLoader manages the loading/downloading and queueing of image requests. Set properties of the shared loader instance to control loading behaviour, or call its loading methods directly to preload images off-screen.

AsyncImageView庫包含了一個AsyncImageView的類,它繼承至UIImageView.這個類實現了不少有用的特性,如自動顯示一個加載的指示器,以及當圖片下載完成後加載時會出現一個漸隱出現的效果.

AsyncImageView也提供了一個AsyncImageLoader類,給高端用戶使用.AsyncImageLoader管理着加載下載以及隊列圖片的請求.設置共享加載的實例變量來達到控制下載行爲的目的,或者,直接預加載圖片便可.

AsyncImageView properties（相關屬性）

The AsyncImageView class has the following properties:

AsyncImageView有着以下的一些屬性:

@property (nonatomic, assign) BOOL showActivityIndicator;

If YES, the AsyncImageView will display a loading spinner when the imageURL is set. This will automatically hide once the image has loaded. Note that this value should bet set before setting the imageURL. Setting this value when loading is already in progress will have no effect. Defaults to YES.

若是設置成YES,AsyncImageView在加載一個網絡的image時會顯示一個加載的菊花,若是image加載完成後,菊花將會消失.注意,你須要在進行網絡請求以前設置這個值.以後設置的話沒有效果了,默認值是YES.

@property (nonatomic, assign) UIActivityIndicatorViewStyle activityIndicatorStyle;

The style that will be used for the UIActivityIndicator (if enabled). Note that this value should bet set beforesetting the imageURL. Setting this value when loading is already in progress will cause the spinner to disappear.

這個顯示菊花樣式的,不過也須要在執行網絡請求以前來設置,若是正在進行網絡請求,此時設置了這個值就會致使菊花消失.

@property (nonatomic, assign) NSTimeInterval crossfadeDuration;

The crossfade animation duration, in seconds. If value is greater than 0, the image will crossfade in once it loads instead of appearing suddenly. Defaults to 0.4.

這是個漸隱動畫的時間週期,以秒計算.若是這個值大於0,當這張圖片已經下載完成以後,這張圖片會漸隱出現,默認值是0.4秒.

AsyncImageLoader notifications（通知事宜）

The AsyncImageLoader can generate the following notifications:

AsyncImageLoader能生成如下的集中通知事宜:

AsyncImageLoadDidFinish

This fires when an image has been loaded. The notification object contains the target object that loaded the image file (e.g. the UIImageView) and the userInfo dictionary contains the following keys:

當圖片已經加載了,就會激活這個通知.這個通知的對象會包含目標相關的一些信息,以下面的這些鍵值:

• AsyncImageImageKey

The UIImage that was loaded.

這個加載的UIImage

• AsyncImageURLKey

The NSURL that the image was loaded from.

這個UIImage加載的URL地址

• AsyncImageCacheKey

The NSCache that the image was stored in.

這個UIImage緩存的地方

AsyncImageLoadDidFail

This fires when an image did not load due to an error. The notification object contains the target object that attempted to load the image file (e.g. the UIImageView) and the userInfo dictionary contains the following keys:

若是圖片由於一個錯誤而沒有加載出來,這個通知就會包含另外的一些鍵值對:

• AsyncImageErrorKey

The NSError generated by the underlying URLConnection.

包換NSError信息

• AsyncImageURLKey

The NSURL that the image failed to load from.

這張圖片的NSURL地址

AsyncImageLoader properties（加載器屬性）

AsyncImageLoader has the following properties:

AsyncImageLoader含有以下的一些屬性:

@property (nonatomic, strong) NSCache *cache;

The cache to be used for image load requests. You can change this value at any time and it will affect all subsequent load requests until it is changed again. By default this is set to [AsyncImageLoader sharedCache]. Set this to nil to disable caching completely, or you can set it to a new NSCache instance or subclass for fine-grained cache control.

圖片請求所用的緩存.你能夠改變這個屬性並瞬間改變全部與之相關的那些子請求.默認值是設置成[AsyncImageLoader sharedCache],將這個值設置成nil會徹底關閉緩存.或者你本身設置成另一個緩存實例來更好的掌握這些緩存.

@property (nonatomic, assign) NSUInteger concurrentLoads;

The number of images to load concurrently. Images are loaded on background threads but loading too many concurrently can choke the CPU. This defaults to 2;

併發加載圖片,若是在後臺併發加載了太多的圖片會噎着CPU的(UI上會卡頓),默認值是2.

@property (nonatomic, assign) NSTimeInterval loadingTimeout;

The loading timeout, in seconds. This defaults to 60, which should be more than enough for loading locally stored images, but may be too short for downloading large images over 3G.

加載的超時時間,以秒計算.默認值是60s,若是用來加載本地圖片,60s太長,可是若是經過3G網絡來加載,這時間也過短了.

AsyncImageLoader methods（加載器相關方法）

AsyncImageLoader has the following methods:

加載器含有以下的一些方法:

- (void)loadImageWithURL:(NSURL *)URL target:(id)target success:(SEL)success failure:(SEL)failure;

This queues an image for download. If the queue is empty and the image is already in cache, this will trigger the success action immediately.

這個是入隊一張圖片來下載的.若是這個隊列是空的,而且這張圖片已經緩存過了,那麼就會當即執行完畢.

The target is retained by the AsyncImageLoader, however the loader will monitor to see if the target is being retained by any other objects, and will release it and terminate the file load if it is not. The target can be nil, in which case the load will still happen as normal and can completion can be detected using the AsyncImageLoadDidFinish and AsyncImageLoadDidFail notifications.

- (void)loadImageWithURL:(NSURL *)URL target:(id)target action:(SEL)action;

Works the same as above, except the action will only be called if the loading is successful. Failure can still be detected using the AsyncImageLoadDidFail notification.

功能和上面的同樣,只是,當圖片成功加載後纔會真正的執行那個方法.你也能夠用失敗的通知來捕捉下載失敗.

- (void)loadImageWithURL:(NSURL *)URL;

Works the same as above, but no target or actions are specified.Use AsyncImageLoadDidFinish and AsyncImageLoadDidFail to detect when the loading is complete.

和上面的功能同樣,只是沒有target以及action,使用通知來捕捉吧是否加載完成吧.

- (void)cancelLoadingURL:(NSURL *)URL target:(id)target action:(SEL)action;

This cancels loading the image with the specified URL for the specified target and action.

取消加載指定的URL圖片.

- (void)cancelLoadingURL:(NSURL *)URL target:(id)target;

This cancels loading the image with the specified URL for any actions on the specified target;

取消目標上的全部的指定下載URL圖片的操做.

- (void)cancelLoadingURL:(NSURL *)URL;

This cancels loading the image with the specified URL.

取消指定加載URL圖片地址.

- (void)cancelLoadingImagesForTarget:(id)target action:(SEL)action;

This cancels loading all queued image URLs with the specified action on the specified target;

取消全部這個指定目標的URL圖片加載.

- (void)cancelLoadingImagesForTarget:(id)target;

This cancels loading all queued image URLs for the specified target;

取消指定目標的全部的加載圖片請求的隊列.

- (NSURL *)URLForTarget:(id)target action:(SEL)action;

This returns the most recent image URL set for the given target and action, which may not be the next one to be loaded if several image URLs have been queued on that target.

返回給指定目標最近的幾回網絡請求加載的URL,但不是按照前後順序的,由於是併發的嘛.

- (NSURL *)URLForTarget:(id)target;

This returns the most recent image URL set for the given target, which may not be the next one to be loaded if several image URLs have been queued on that target.

同上

Usage（使用）

You can use the AsyncImageView class exactly as you would use a UIImageView. If you want to use it in Interface Builder, drag a regular UImageView or media image into your view as normal, then change its class to AsyncImageView in the inspector.

你能夠像使用UIImageView那樣來使用AsyncImageView,若是你想在IB裏面使用,你直接拖拽UImageView到你的空間中,而後替換掉類名便可.

For cases where you cannot use an AsyncImageView, such as the embedded imageView of a UIButton or UITableView, the UIImageView category means that you can still set the imageURL property on the imageView to load the image in the background. You will not get the advanced features of the AsyncImageView class this way however (such as the loading spinner), unless you re-implement them yourself.

某些狀況下你沒法使用AsyncImageView,例如植入到UIButton或者UITableView上的圖片,可是,UIImageView類目仍是能夠幫助你在後臺設置imageURL屬性的.在這種情形下,你就不能使用AsyncImageView的對象了,除非你本身去從新實現他們.

To load or download an image, simply set the imageURL property to the URL of the desired image. This can be a remote URL or a local fileURL that points to the application's bundle or documents folder.

加載一張圖片或者系統內的圖片,簡單的設置imageURL,他能夠加載本地的或者網絡上的圖片.

If you want to display a placeholder image in the meantime, just manually set the image property of the UIImageView to your placeholder image and it will be overwritten once the image specified by the URL has loaded.

若是你想在加載圖片的時候顯示一張placeholder圖片,請手動設置你的UIImageView屬性到這張圖片上,當網絡請求完成後,會自動替換的.

If you want to asynchronously load a smaller thumbnail image while the main image loads, just set the thumbnail URL first, then the full image URL. AsyncImageLoader will ensure that the images are loaded in the correct order. If the larger image is already cached, or loads first for some reason, the thumbnail image loading will be cancelled.

若是你想同時加載同一張圖片的小圖和大圖,先設置 thumbnail URL地址,再設置大圖的 URL地址.AsyncImageLoader會確保準確的加載順序,若是大圖以前緩存過了,那麼會取消加載小圖的.

To detect when the image has finished loading, you can use NSNotificationCenter in conjunction with the AsyncImageLoadDidFinish notification, or you can use KVO (Key-Value Observation) to set up an observer on the UIImageView's image property. When the image has finished loading, the image will be set, and with KVO you can detect this and react accordingly.

爲了監測圖片是否加載完畢,你可使用NSNotificationCenter來獲取加載的通知,或者你經過KVO來設置監聽者來監聽這些,當圖片加載完成後,就會被設置上,KVO就會直接監聽到這個舉動.

By default, all loaded images are cached, and if the app loads a large number of images, the cache will keep building up until a memory warning is triggered. You can avoid memory warnings by manually removing items from the cache according to your own maintenance logic. You can also disable caching either universally or for specific images by setting the shared AsyncImageLoader's cache property to nil before loading an image (set it back to [AsyncImageLoader sharedInstance] to re-enable caching afterwards).

默認狀況下,全部圖片都是緩存起來的,若是app加載了不少大的圖片,那麼緩存就會愈來愈大知道出現內存警告.你能夠根據邏輯來刪除那些你不要的那些圖片,你也能夠不用緩存圖片每回直接從網絡請求也是可行的.

 

 

心得:

1. 該AsyncImageView不是基於GCD的,因此使用在UITableView或者UIButton中會出現一些使用上的限制

2. 能夠加載圖片序列,先加載小圖再加載大圖

3. 加載圖片的時候能夠顯示出菊花

4. 圖片成功加載後會有着漸隱出現的效果

5. 圖片是否加載成功經過通知中心來實現

6. 比不上SDWebImage,但也有本身的亮點,仍是挺好用的.