SDWebImage ReadMe.md 文檔
附：SDWebImage框架github下載地址:https://github.com/rs/SDWebImage注1：該文章簡單翻譯了SDWebImage最新版本（3.7.5）的readMe.md。
Web Image
版本3.7.5|平臺iOS|開源協議MIT|
該庫爲UIImageView提供了一個分類來處理遠程圖片資源的加載。
它：
1）爲Cocoa Touch框架提供一個UIImageView的分類，加載圖片並進行緩存處理。
2）異步圖像下載
3）異步存儲器+具備自動緩存過期處理的磁盤映像緩存
4）支持GIF播放
5）支持WebP格式
6）背景圖像解壓縮
7）保證同一個url圖片資源不被多次下載
8）保證錯誤url不被反覆嘗試下載
9）保證不會阻塞主線程
10）高性能
11）使用GCD和ARC
12）支持Arm64架構
注：SDWebimage3.0版本並沒有完全向後兼容2.0版本且要求的最低配置爲iOS5.1.1版本。如果你需要在iOS5.0以前的版本使用，那麼請您使用2.0版本。
How is SDWebImage better than X?
- <code class="hljs objectivec" style="margin:auto; vertical-align:top; display:block; overflow-x:auto; line-height:1.5!important; font-family:'Courier New',sans-serif!important; font-size:12px!important; border:1px solid rgb(204,204,204)!important; padding:5px!important"><span style="background-color:rgb(255,255,255)">·AFNetworking已經提供<span class="hljs-built_in" style="color:rgb(0,0,255)">UIImageView</span>相似的功能，還有必要使用SDWebimage嗎？</span></code>
Who Use It（誰用）
查看哪些應用使用了SDWebImage框架，添加你的應用到列表。
How To Use（如何用）
查看api文檔CocoaDocs - SDWebImage
TableView加載圖片使用UIImageView+WebCache分類
只需要包含UIImageView+WebCache.h頭文件，並在tableView的數據源方法tableView:cellForRowAtIndexPath: 中調用sd_setImageWithURL:placeholderImage:方法即可。異步下載和緩存處理這一切都將會自動爲你處理。
- <code class="hljs objectivec" style="margin:auto; vertical-align:top; display:block; overflow-x:auto; line-height:1.5!important; font-family:'Courier New',sans-serif!important; font-size:12px!important; border:1px solid rgb(204,204,204)!important; padding:5px!important"><span style="background-color:rgb(255,255,255)"><span class="hljs-meta" style="color:rgb(43,145,175)">#import <span class="hljs-meta-string"><SDWebImage/UIImageView+WebCache.h></span></span>
- ...
- - (<span class="hljs-built_in" style="color:rgb(0,0,255)">UITableViewCell</span> *)tableView:(<span class="hljs-built_in" style="color:rgb(0,0,255)">UITableView</span> *)tableView cellForRowAtIndexPath:(<span class="hljs-built_in" style="color:rgb(0,0,255)">NSIndexPath</span> *)indexPath {
- <span class="hljs-keyword" style="color:rgb(0,0,255)">static</span> <span class="hljs-built_in" style="color:rgb(0,0,255)">NSString</span> *MyIdentifier = <span class="hljs-string" style="color:rgb(163,21,21)">@"MyIdentifier"</span>;
- <span class="hljs-built_in" style="color:rgb(0,0,255)">UITableViewCell</span> *cell = [tableView dequeueReusableCellWithIdentifier:MyIdentifier];
- <span class="hljs-keyword" style="color:rgb(0,0,255)">if</span> (cell == <span class="hljs-literal" style="color:rgb(163,21,21)">nil</span>) {
- cell = [[[<span class="hljs-built_in" style="color:rgb(0,0,255)">UITableViewCell</span> alloc] initWithStyle:<span class="hljs-built_in" style="color:rgb(0,0,255)">UITableViewCellStyleDefault</span>
- reuseIdentifier:MyIdentifier] autorelease];
- }
- <span class="hljs-comment" style="color:green">// Here we use the new provided sd_setImageWithURL: method to load the web image</span>
- [cell.imageView sd_setImageWithURL:[<span class="hljs-built_in" style="color:rgb(0,0,255)">NSURL</span> URLWithString:<span class="hljs-string" style="color:rgb(163,21,21)">@"http://www.domain.com/path/to/image.jpg"</span>]
- placeholderImage:[<span class="hljs-built_in" style="color:rgb(0,0,255)">UIImage</span> imageNamed:<span class="hljs-string" style="color:rgb(163,21,21)">@"placeholder.png"</span>]];
- cell.textLabel.text = <span class="hljs-string" style="color:rgb(163,21,21)">@"My Text"</span>;
- <span class="hljs-keyword" style="color:rgb(0,0,255)">return</span> cell;
- }</span></code>
使用Blocks
使用block，你將能夠得到圖片的下載進度並獲知圖片是否下載成功或者失敗：
- <code class="hljs objectivec" style="margin:auto; vertical-align:top; display:block; overflow-x:auto; line-height:1.5!important; font-family:'Courier New',sans-serif!important; font-size:12px!important; border:1px solid rgb(204,204,204)!important; padding:5px!important"><span style="background-color:rgb(255,255,255)"><span class="hljs-comment" style="color:green">// Here we use the new provided sd_setImageWithURL: method to load the web image</span>
- [cell.imageView sd_setImageWithURL:[<span class="hljs-built_in" style="color:rgb(0,0,255)">NSURL</span> URLWithString:<span class="hljs-string" style="color:rgb(163,21,21)">@"http://www.domain.com/path/to/image.jpg"</span>]
- placeholderImage:[<span class="hljs-built_in" style="color:rgb(0,0,255)">UIImage</span> imageNamed:<span class="hljs-string" style="color:rgb(163,21,21)">@"placeholder.png"</span>]
- completed:^(<span class="hljs-built_in" style="color:rgb(0,0,255)">UIImage</span> *image, <span class="hljs-built_in" style="color:rgb(0,0,255)">NSError</span> *error, SDImageCacheType cacheType, <span class="hljs-built_in" style="color:rgb(0,0,255)">NSURL</span> *imageURL) {
- ... completion code here ...
- }];</span></code>
注意：如果圖像請求在完成前被取消了，那麼成功和失敗的block塊將都不會被調用。
使用SDWebImageManager
UIImageView+WebCache分類背後調用的是SDWebImageManager類的方法，負責圖像的異步下載和緩存處理。你可以直接使用這個類來下載圖片和進行緩存處理。
這有一個如何使用SDWebImageManager的簡單示例：
- <code class="hljs objectivec" style="margin:auto; vertical-align:top; display:block; overflow-x:auto; line-height:1.5!important; font-family:'Courier New',sans-serif!important; font-size:12px!important; border:1px solid rgb(204,204,204)!important; padding:5px!important"><span style="background-color:rgb(255,255,255)">SDWebImageManager *manager = [SDWebImageManager sharedManager];
- [manager downloadImageWithURL:imageURL
- options:<span class="hljs-number">0</span>
- progress:^(<span class="hljs-built_in" style="color:rgb(0,0,255)">NSInteger</span> receivedSize, <span class="hljs-built_in" style="color:rgb(0,0,255)">NSInteger</span> expectedSize) {
- <span class="hljs-comment" style="color:green">// progression tracking code</span>
- }
- completed:^(<span class="hljs-built_in" style="color:rgb(0,0,255)">UIImage</span> *image, <span class="hljs-built_in" style="color:rgb(0,0,255)">NSError</span> *error, SDImageCacheType cacheType, <span class="hljs-built_in" style="color:rgb(0,0,255)">BOOL</span> finished, <span class="hljs-built_in" style="color:rgb(0,0,255)">NSURL</span> *imageURL) {
- <span class="hljs-keyword" style="color:rgb(0,0,255)">if</span> (image) {
- <span class="hljs-comment" style="color:green">// do something with image</span>
- }
- }];</span></code>
單獨異步下載圖片
它也可以獨立使用異步圖片下載：
- <code class="hljs objectivec" style="margin:auto; vertical-align:top; display:block; overflow-x:auto; line-height:1.5!important; font-family:'Courier New',sans-serif!important; font-size:12px!important; border:1px solid rgb(204,204,204)!important; padding:5px!important"><span style="background-color:rgb(255,255,255)">SDWebImageDownloader *downloader = [SDWebImageDownloader sharedDownloader];
- [downloader downloadImageWithURL:imageURL
- options:<span class="hljs-number">0</span>
- progress:^(<span class="hljs-built_in" style="color:rgb(0,0,255)">NSInteger</span> receivedSize, <span class="hljs-built_in" style="color:rgb(0,0,255)">NSInteger</span> expectedSize) {
- <span class="hljs-comment" style="color:green">// progression tracking code</span>
- }
- completed:^(<span class="hljs-built_in" style="color:rgb(0,0,255)">UIImage</span> *image, <span class="hljs-built_in" style="color:rgb(0,0,255)">NSData</span> *data, <span class="hljs-built_in" style="color:rgb(0,0,255)">NSError</span> *error, <span class="hljs-built_in" style="color:rgb(0,0,255)">BOOL</span> finished) {
- <span class="hljs-keyword" style="color:rgb(0,0,255)">if</span> (image && finished) {
- <span class="hljs-comment" style="color:green">// do something with image</span>
- }
- }];</span></code>
單獨異步緩存圖片
也可以單獨使用基於圖像的高速異步緩存處理。SDImagecache提供內存高速緩存和可選的磁盤高速緩存。磁盤高速緩存寫入操作是異步的，所以不需要在用戶界面添加不必要的延遲。
爲了方便，SDImageCache類提供了一個單一的實例，但如果你想自定義緩存空間，那麼可以創建自己的實例。
您可以使用queryDiskCacheForKey：done：方法查找緩存。如果該方法返回nil，則說明當前image沒有緩存。你需要負責下載和進行緩存處理。圖像緩存的key通常爲該圖像的URL。
- <code class="hljs objectivec" style="margin:auto; vertical-align:top; display:block; overflow-x:auto; line-height:1.5!important; font-family:'Courier New',sans-serif!important; font-size:12px!important; border:1px solid rgb(204,204,204)!important; padding:5px!important"><span style="background-color:rgb(255,255,255)">SDImageCache *imageCache = [[SDImageCache alloc] initWithNamespace:<span class="hljs-string" style="color:rgb(163,21,21)">@"myNamespace"</span>];
- [imageCache queryDiskCacheForKey:myCacheKey done:^(<span class="hljs-built_in" style="color:rgb(0,0,255)">UIImage</span> *image) {
- <span class="hljs-comment" style="color:green">// image is not nil if image was found</span>
- }];</span></code>
默認情況下，如果對應圖片的內存緩存不存在，那麼SDImageCache將查找磁盤緩存。可以通過調用imageFromMemoryCacheForKey：方法來阻止。
你可以調用storeImage:forKey: method:方法保存圖片到緩存。
- <code class="hljs objectivec" style="margin:auto; vertical-align:top; display:block; overflow-x:auto; line-height:1.5!important; font-family:'Courier New',sans-serif!important; font-size:12px!important; border:1px solid rgb(204,204,204)!important; padding:5px!important"><span style="background-color:rgb(255,255,255)">[[SDImageCache sharedImageCache] storeImage:myImage forKey:myCacheKey];</span></code>
默認情況下，圖像將被進行內存緩存和磁盤緩存（異步）。如果你只想要內存緩存，那麼可以使用storeImage:forKey:toDisk:方法，第三個參數傳NO即可。
使用緩存key篩選器
有時，你可能會因爲URL的一部分是動態的而不希望使用URL作爲圖像緩存的key。 SDWebImageManager提供了一種方式來設置，輸入URL輸出對應的字符串。
下面的示例在應用程序的委託中設置一個過濾器，在使用它的緩存鍵之前將從URL中刪除任何查詢字符串
- <code class="hljs objectivec" style="margin:auto; vertical-align:top; display:block; overflow-x:auto; line-height:1.5!important; font-family:'Courier New',sans-serif!important; font-size:12px!important; border:1px solid rgb(204,204,204)!important; padding:5px!important"><span style="background-color:rgb(255,255,255)">- (<span class="hljs-built_in" style="color:rgb(0,0,255)">BOOL</span>)application:(<span class="hljs-built_in" style="color:rgb(0,0,255)">UIApplication</span> *)application didFinishLaunchingWithOptions:(<span class="hljs-built_in" style="color:rgb(0,0,255)">NSDictionary</span> *)launchOptions {
- SDWebImageManager.sharedManager.cacheKeyFilter = ^(<span class="hljs-built_in" style="color:rgb(0,0,255)">NSURL</span> *url) {
- url = [[<span class="hljs-built_in" style="color:rgb(0,0,255)">NSURL</span> alloc] initWithScheme:url.scheme host:url.host path:url.path];
- <span class="hljs-keyword" style="color:rgb(0,0,255)">return</span> [url absoluteString];
- };
- <span class="hljs-comment" style="color:green">// Your app init code...</span>
- <span class="hljs-keyword" style="color:rgb(0,0,255)">return</span> <span class="hljs-literal" style="color:rgb(163,21,21)">YES</span>;
- }</span></code>
常見問題
使用動態圖像大小的UITableViewCell
UITableViewCell通過第一個單元格設置的圖像決定圖像的尺寸。如果你加載的網絡圖片和佔位符圖像尺寸不一致，那麼您可能會遇到奇怪的變形比例問題。下面的文章給出瞭解決此問題的方法：
http://www.wrichards.com/blog/2011/11/sdwebimage-fixed-width-cell-images/
處理圖像刷新
SDWebimage默認情況下做了很好的緩存處理。它忽略通過HTTP服務器返回的所有類型的緩存控制頭，並且沒有時間限制地緩存返回的圖像
它意味着你的url指向的圖片是一成不變的。更好的做法是如果url指向的圖片發生了改變，那麼圖片也應該變化。
在這種情況下，你可以使用SDWebImageRefreshCached標誌。這將略微降低性能，但會尊重HTTP緩存控制頭：
- <code class="hljs objectivec" style="margin:auto; vertical-align:top; display:block; overflow-x:auto; line-height:1.5!important; font-family:'Courier New',sans-serif!important; font-size:12px!important; border:1px solid rgb(204,204,204)!important; padding:5px!important"><span style="background-color:rgb(255,255,255)">
- [imageView sd_setImageWithURL:[<span class="hljs-built_in" style="color:rgb(0,0,255)">NSURL</span> URLWithString:<span class="hljs-string" style="color:rgb(163,21,21)">@"https://graph.facebook.com/olivier.poitrey/picture"</span>]
- placeholderImage:[<span class="hljs-built_in" style="color:rgb(0,0,255)">UIImage</span> imageNamed:<span class="hljs-string" style="color:rgb(163,21,21)">@"avatar-placeholder.png"</span>]
- options:SDWebImageRefreshCached];</span></code>
添加進度指示器
參考：https://github.com/JJSaccolo/UIActivityIndicator-for-SDWebImage
安裝
有三種方法把SDWebImage安裝到您的項目中：
- <code class="hljs objectivec" style="margin:auto; vertical-align:top; display:block; overflow-x:auto; line-height:1.5!important; font-family:'Courier New',sans-serif!important; font-size:12px!important; border:1px solid rgb(204,204,204)!important; padding:5px!important"><span style="background-color:rgb(255,255,255)"><span class="hljs-number">1</span>）使用Cocoapods
- <span class="hljs-number">2</span>）複製所有文件到您的項目
- <span class="hljs-number">3</span>）作爲靜態庫導入項目</span></code>