225 lines
8.5 KiB
Markdown
225 lines
8.5 KiB
Markdown
Web Image
|
||
=========
|
||
|
||
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
|
||
- An asynchronous image downloader
|
||
- An asynchronous memory + disk image caching with automatic cache expiration handling
|
||
- A background image decompression
|
||
- A guarantee that the same URL won't be downloaded several times
|
||
- A guarantee that bogus URLs won't be retried again and again
|
||
- A guarantee that main thread will never be blocked
|
||
- Performances!
|
||
|
||
[How is SDWebImage better than X?](https://github.com/rs/SDWebImage/wiki/How-is-SDWebImage-better-than-X%3F)
|
||
|
||
Who Use It
|
||
----------
|
||
|
||
Find out [who use SDWebImage](https://github.com/rs/SDWebImage/wiki/Who-Use-SDWebImage) and add your app to the list.
|
||
|
||
How To Use
|
||
----------
|
||
|
||
API documentation is available at [http://hackemist.com/SDWebImage/doc/](http://hackemist.com/SDWebImage/doc/)
|
||
|
||
### Using UIImageView+WebCache category with UITableView
|
||
|
||
Just #import the UIImageView+WebCache.h header, and call the setImageWithURL:placeholderImage:
|
||
method from the tableView:cellForRowAtIndexPath: UITableViewDataSource method. Everything will be
|
||
handled for you, from async downloads to caching management.
|
||
|
||
```objective-c
|
||
#import <SDWebImage/UIImageView+WebCache.h>
|
||
|
||
...
|
||
|
||
- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath
|
||
{
|
||
static NSString *MyIdentifier = @"MyIdentifier";
|
||
|
||
UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:MyIdentifier];
|
||
|
||
if (cell == nil)
|
||
{
|
||
cell = [[[UITableViewCell alloc] initWithStyle:UITableViewCellStyleDefault
|
||
reuseIdentifier:MyIdentifier] autorelease];
|
||
}
|
||
|
||
// Here we use the new provided setImageWithURL: method to load the web image
|
||
[cell.imageView setImageWithURL:[NSURL URLWithString:@"http://www.domain.com/path/to/image.jpg"]
|
||
placeholderImage:[UIImage imageNamed:@"placeholder.png"]];
|
||
|
||
cell.textLabel.text = @"My Text";
|
||
return cell;
|
||
}
|
||
```
|
||
|
||
### Using blocks
|
||
|
||
If your project's deployement target is set to iOS 4+, you may want to use the success/failure blocks to be
|
||
notified when image have been retrieved from cache.
|
||
```objective-c
|
||
// Here we use the new provided setImageWithURL: method to load the web image
|
||
[cell.imageView setImageWithURL:[NSURL URLWithString:@"http://www.domain.com/path/to/image.jpg"]
|
||
placeholderImage:[UIImage imageNamed:@"placeholder.png"]
|
||
success:^(UIImage *image, BOOL cached) {... success code here ...}
|
||
failure:^(NSError *error) {... failure code here ...}];
|
||
];
|
||
```
|
||
|
||
Note: neither your success nor failure block will be call if your image request is canceled before completion.
|
||
|
||
### Using SDWebImageManager
|
||
|
||
The SDWebImageManager is the class behind the UIImageView+WebCache category. 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).
|
||
|
||
Here is a simple example of how to use SDWebImageManager:
|
||
|
||
```objective-c
|
||
SDWebImageManager *manager = [SDWebImageManager sharedManager];
|
||
[manager downloadWithURL:imageURL
|
||
delegate:self
|
||
options:0
|
||
success:^(UIImage *image, BOOL cached)
|
||
{
|
||
// do something with image
|
||
}
|
||
failure:nil];
|
||
```
|
||
|
||
### Using Asynchronous Image Downloader Independently
|
||
|
||
It is possible to use the async image downloader independently. You just have to create an instance
|
||
of SDWebImageDownloader using its convenience constructor downloaderWithURL:delegate:.
|
||
```objective-c
|
||
downloader = [SDWebImageDownloader downloaderWithURL:url delegate:self];
|
||
```
|
||
|
||
The download will start immediately and the imageDownloader:didFinishWithImage: method from the
|
||
SDWebImageDownloaderDelegate protocol will be called as soon as the download of image is completed.
|
||
|
||
### Using Asynchronous Image Caching Independently
|
||
|
||
It is also possible to use the NSOperation 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.
|
||
|
||
The SDImageCache class provides a singleton instance for convenience but you can create your own
|
||
instance if you want to create separated cache namespace.
|
||
|
||
To lookup the cache, you use the imageForKey: 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.
|
||
|
||
```objective-c
|
||
UIImage *myCachedImage = [[SDImageCache sharedImageCache] imageFromKey:myCacheKey];
|
||
```
|
||
|
||
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 imageFromKey:fromDisk: with a
|
||
negative second argument.
|
||
|
||
To store an image into the cache, you use the storeImage:forKey: method:
|
||
|
||
```objective-c
|
||
[[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
|
||
|
||
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.
|
||
|
||
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:
|
||
|
||
```objective-c
|
||
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
|
||
{
|
||
[[SDWebImageManager sharedManager] setCacheKeyFilter:^(NSURL *url)
|
||
{
|
||
url = [[[NSURL alloc] initWithScheme:url.scheme host:url.host path:url.path] autorelease];
|
||
return [url absoluteString];
|
||
}];
|
||
|
||
// Your app init code...
|
||
return YES;
|
||
}
|
||
```
|
||
|
||
|
||
Common Problems
|
||
---------------
|
||
|
||
### Using dynamic image size with UITableViewCell
|
||
|
||
UITableView determins 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/](http://www.wrichards.com/blog/2011/11/sdwebimage-fixed-width-cell-images/)
|
||
|
||
Automatic Reference Counting (ARC)
|
||
----------------------------------
|
||
|
||
You can use either style in your Cocoa project. SDWebImage Will figure out which you are using at compile
|
||
time and do the right thing.
|
||
|
||
|
||
Installation
|
||
------------
|
||
|
||
There are two ways to use this in your project: copy all the files into your project, or import the project as a static library.
|
||
|
||
### Add the SDWebImage project to your project
|
||
|
||
- Download and unzip the last version of the framework from the [download page](https://github.com/rs/SDWebImage/downloads)
|
||
- Right-click on the project navigator and select "Add Files to "Your Project":
|
||
- In the dialog, select SDWebImage.framework:
|
||
- Check the "Copy items into destination group's folder (if needed)" checkbox
|
||
|
||
### Add dependencies
|
||
|
||
- In you application project app’s target settings, find the "Build Phases" section and open the "Link Binary With Libraries" block:
|
||
- Click the "+" button again and select the "ImageIO.framework", this is needed by the progressive download feature:
|
||
|
||
### Add Linker Flag
|
||
|
||
Open the "Build Settings" tab, in the "Linking" section, locate the "Other Linker Flags" setting and add the "-ObjC" flag:
|
||
|
||
|
||
|
||
### Import headers in your source files
|
||
|
||
In the source files where you need to use the library, import the header file:
|
||
|
||
```objective-c
|
||
#import <SDWebImage/UIImageView+WebCache.h>
|
||
```
|
||
|
||
### Build Project
|
||
|
||
At this point your workspace should build without error. If you are having problem, post to the Issue and the
|
||
community can help you solve it.
|
||
|
||
Future Enhancements
|
||
-------------------
|
||
|
||
- LRU memory cache cleanup instead of reset on memory warning
|
||
|
||
## Licenses
|
||
|
||
All source code is licensed under the [MIT License](https://raw.github.com/rs/SDWebImage/master/LICENSE).
|