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>