This library provides a category for UIImageView(图片分类) with support for remote images coming from the web(应用于网络远程图片).
It provides:(功能有:)
An UIImageView category adding web image and cache management to the Cocoa Touch framework(UIImageVIew的分类和缓存管理)
An asynchronous image downloader(异步的图片下载器)
An asynchronous memory + disk image caching with automatic cache expiration handling(异步的内存缓存和磁盘缓存(沙盒缓存))--------------缓存期
Animated GIF support(支持动态图)
WebP format support(支持WebP格式)
A background image decompression(后台解压图片)
A guarantee that the same URL won't be downloaded several times(同一个URL不会发送请求多次的机制)----------------操作缓存机制
A guarantee that bogus URLs won't be retried again and again(防黑客攻击)
A guarantee that main thread will never be blocked(主线程不会卡顿的机制)
Performances!
Use GCD and ARC
Arm64 support
NOTE: Version 3.8 of SDWebImage requires iOS 7 or later (because of NSURLSession). Versions 3.7 to 3.0 requires iOS 5.1.1. If you need iOS < 5.0 support, please use the last 2.0 version.
How is SDWebImage better than X?(NSURLCache, NSCache, NSURLRequest,NSURLSession)
How To Use
Using UIImageView+WebCache category with UITableView
Just #import the UIImageView+WebCache.h header, and call the sd_setImageWithURL:placeholderImage: method from the tableView:cellForRowAtIndexPath: UITableViewDataSource method. Everything will be handled for you, from async downloads to caching management.
With blocks, you can be notified about the image download progress and whenever the image retrieval has completed with success or not:
[cell.imageView sd_setImageWithURL:[NSURL URLWithString:@"http://www.domain.com/path/to/image.jpg"]
placeholderImage:[UIImage imageNamed:@"placeholder.png"]
completed:^(UIImage *image, NSError *error, SDImageCacheType cacheType, NSURL *imageURL) {
... completion code here ...
}];
Note: neither your success nor failure block will be call if your image request is canceled before completion.(即使图片请求被取消了(完成之前),无论是successBlock,还是failureBlock都会被调用的)
Using SDWebImageManager(网络图片下载管理器)
The SDWebImageManager is the class behind the UIImageView+WebCache category.
(SDWebImageManager图片下载管理器是支持UIImageView+WebCache分类的)It ties the asynchronous downloader with the image cache store.(该下载管理器把异步下载器和图片缓存区紧紧地捆绑在一起.) You can use this class directly to benefit from web image downloading with caching in another context than a UIView (ie: with Cocoa).(可以使用该类给任意一个UIView类的上下文(不限于UIImageView)用缓存的方式下载网络图片).
Here is a simple example of how to use SDWebImageManager:
SDWebImageManager *manager = [SDWebImageManager sharedManager];
[manager downloadImageWithURL:imageURL
options:0
progress:^(NSInteger receivedSize, NSInteger expectedSize) {
// progression tracking code
}
completed:^(UIImage *image, NSError *error, SDImageCacheType cacheType, BOOL finished, NSURL *imageURL) {
if (image) {
// do something with image
}
}];
Using Asynchronous Image Downloader Independently(异步图片下载器)
Using Asynchronous Image Caching Independently(异步线程中的图片缓存)
It is also possible to use the async based image cache store independently. SDImageCache maintains a memory cache and an optional disk cache. Disk cache write operations are performed asynchronous so it doesn't add unnecessary latency to the UI.(磁盘缓存的写入操作是异步的. 没有给UI线程添加任何卡顿)
The SDImageCache class provides a singleton instance for convenience but you can create your own instance if you want to create separated cache namespace.
(SDImageCache类提供了单例便捷构造器. 同时,如果你想自己创建其他的缓存控件,也可以创建自己的SDImageCache实例)
To lookup the cache, you use the queryDiskCacheForKey:done: method. If the method returns nil, it means the cache doesn't currently own the image. You are thus responsible for generating and caching it. The cache key is an application unique identifier for the image to cache. It is generally the absolute URL of the image.(缓存key.一般由图片的绝对路径生成)
SDImageCache *imageCache = [[SDImageCache alloc] initWithNamespace:@"myNamespace"];
[imageCache queryDiskCacheForKey:myCacheKey done:^(UIImage *image) {
// image is not nil if image was found
}];
By default SDImageCache will lookup the disk cache if an image can't be found in the memory cache. You can prevent this from happening by calling the alternative method imageFromMemoryCacheForKey:.
To store an image into the cache, you use the storeImage:forKey: method:
[[SDImageCache sharedImageCache] storeImage:myImage forKey:myCacheKey];
By default(默认情况下), the image will be stored in memory cache as well as on disk cache (asynchronously内存缓存和磁盘缓存是异步的<异步意味着同时>). If you want only the memory cache, use the alternative method storeImage:forKey:toDisk: with a negative third argument.(可以通过不遵守第三方协议,可以不用磁盘缓存)
Using cache key filter(缓存中key值的过滤)
Sometime, you may not want to use the image URL as cache key because part of the URL is dynamic (i.e.: for access control purpose). SDWebImageManager provides a way to set a cache key filter that takes the NSURL as input, and output a cache key NSString.(有时,你可能不想使用URL的key值,作为图片的缓存key.)
The following example sets a filter in the application delegate that will remove any query-string from the URL before to use it as a cache key:
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
SDWebImageManager.sharedManager.cacheKeyFilter = ^(NSURL *url) {
url = [[NSURL alloc] initWithScheme:url.scheme host:url.host path:url.path];
return [url absoluteString];
};
// Your app init code...
return YES;
}
Common Problems(共性问题)
Using dynamic image size(变化的图片尺寸) with UITableViewCell
UITableView determines the size of the image by the first image set for a cell. If your remote images don't have the same size as your placeholder image, you may experience strange anamorphic scaling issue. The following article gives a way to workaround this issue(解决此问题):
http://www.wrichards.com/blog/2011/11/sdwebimage-fixed-width-cell-images/
Handle image refresh
SDWebImage does very aggressive caching by default. It ignores all kind of caching control header returned by the HTTP server and cache the returned images with no time restriction. It implies your images URLs are static URLs pointing to images that never change. If the pointed image happen to change, some parts of the URL should change accordingly.
If you don't control the image server you're using, you may not be able to change the URL when its content is updated. This is the case for Facebook avatar URLs for instance. In such case, you may use the SDWebImageRefreshCached flag. This will slightly degrade the performance but will respect the HTTP caching control headers:
[imageView sd_setImageWithURL:[NSURL URLWithString:@"https://graph.facebook.com/olivier.poitrey/picture"]
placeholderImage:[UIImage imageNamed:@"avatar-placeholder.png"]
options:SDWebImageRefreshCached];
There are three ways to use SDWebImage in your project:
using CocoaPods
copying all the files into your project
importing the project as a static library
两个单例:图片下载管理器和 SDImageCache.
