[翻譯] AsyncImageView 異步下載下傳圖檔

asyncimageview 

<a href="https://github.com/nicklockwood/asyncimageview" target="_blank">https://github.com/nicklockwood/asyncimageview</a>

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。

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 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。

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 &gt; refactor &gt; 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&gt;refactor&gt;convert to objective-c arc... 工具，確定所有要轉換成arc的檔案都檢查過了而沒有遺漏。

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是線程安全的，你不能設定任何的相關線程的屬性，除非在主線程上。

to use the asyncimageview in an app, just drag the asyncimageview class files into your project.

僅需将asyncimageview 檔案夾拖入到你的工程項目中即可。

the basic interface of asyncimageview is a category that extends uiimageview with the following property:

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

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 <code>-cancelloadingurl:target:</code> method on the asyncimageloader class, passing the uiimageview instance as the target (see below).

如果你用了這個屬性設定了很多圖檔，他将會傳回你設定過的那些圖檔的 url 位址，但是并不一定按照你指定的順序來加載（因為是并發線程嘛），如果你想取消目前加載中的圖檔，使用-cancelloadingurl:target:方法來取消，給uiimageview的一個執行個體對象使用該方法。

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管理着加載下載下傳以及隊列圖檔的請求.設定共享加載的執行個體變量來達到控制下載下傳行為的目的,或者,直接預加載圖檔即可.

the asyncimageview class has the following properties:

asyncimageview有着如下的一些屬性:

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.

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.

這個顯示菊花樣式的,不過也需要在執行網絡請求之前來設定,如果正在進行網絡請求,此時設定了這個值就會導緻菊花消失.

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秒.

the asyncimageloader can generate the following notifications:

asyncimageloader能生成以下的集中通知事宜:

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緩存的地方

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資訊

the nsurl that the image failed to load from.

這張圖檔的nsurl位址

asyncimageloader has the following properties:

asyncimageloader含有如下的一些屬性:

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 <code>[asyncimageloader sharedcache]</code>. 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.

圖檔請求所用的緩存.你可以改變這個屬性并瞬間改變所有與之相關的那些子請求.預設值是設定成<code>[asyncimageloader sharedcache],将這個值設定成nil會完全關閉緩存.或者你自己設定成另外一個緩存執行個體來更好的掌握這些緩存.</code>

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.

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 has the following methods:

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

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 <code>asyncimageloaddidfinish</code> and <code>asyncimageloaddidfail</code> notifications.

works the same as above, except the action will only be called if the loading is successful. failure can still be detected using the <code>asyncimageloaddidfail</code> notification.

功能和上面的一樣,隻是,當圖檔成功加載後才會真正的執行那個方法.你也可以用失敗的通知來捕捉下載下傳失敗.

works the same as above, but no target or actions are specified.use <code>asyncimageloaddidfinish</code> and <code>asyncimageloaddidfail</code> to detect when the loading is complete.

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

this cancels loading the image with the specified url for the specified target and action.

取消加載指定的url圖檔.

this cancels loading the image with the specified url for any actions on the specified target;

取消目标上的所有的指定下載下傳url圖檔的操作.

this cancels loading the image with the specified url.

取消指定加載url圖檔位址.

this cancels loading all queued image urls with the specified action on the specified target;

取消所有這個指定目标的url圖檔加載.

this cancels loading all queued image urls for the specified target;

取消指定目标的所有的加載圖檔請求的隊列.

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,但不是按照先後順序的,因為是并發的嘛.

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.

同上

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 <code>asyncimageloaddidfinish</code> 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 <code>nil</code> before loading an image (set it back to <code>[asyncimageloader sharedinstance]</code> to re-enable caching afterwards).

預設情況下,所有圖檔都是緩存起來的,如果app加載了很多大的圖檔,那麼緩存就會越來越大知道出現記憶體警告.你可以根據邏輯來删除那些你不要的那些圖檔,你也可以不用緩存圖檔每回直接從網絡請求也是可行的.

心得:

1. 該asyncimageview不是基于gcd的,是以使用在uitableview或者uibutton中會出現一些使用上的限制

2. 可以加載圖檔序列,先加載小圖再加載大圖

3. 加載圖檔的時候可以顯示出菊花

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

5. 圖檔是否加載成功通過通知中心來實作

6. 比不上sdwebimage,但也有自己的亮點,還是挺好用的.