Repository files navigation

A high performance Swift library for downloading, caching and editing web images asynchronously.

中文介绍

Simplely download, display and cache images.

Download images. Decode, edit and display images while downloading. After downloading, cache edited images to memory and cache original image data to disk.

• Add filter

• Draw rounded corner and border

Test libraries are BBWebImage (1.1.0), SDWebImage (4.4.6 and FLAnimatedImage 1.0.12 for GIF), YYWebImage (1.0.5) and Kingfisher (4.10.1). Test device is iPhone 7 with iOS 12.1. The code can be found inCompareImageLib project and the test result data can be found inCompareImageLib.numbers.

• BBWebImage has high speed memory and disk cache, especially for thumbnail image.

• BBWebImage consumes low CPU and memory when loading and displaying GIF.

• View extensions forUIImageView,UIButton,MKAnnotationView andCALayer to set image from URL
• Asynchronous image downloader
• Asynchronous memory + file + SQLite image cache with least recently used algorithm
• Asynchronous image decompressing
• Asynchronous image editing without modifying original image disk data
• Animated image smart decoding, decompressing, editing and caching
• Independent image cache, downloader, coder and editor for separate use
• Customized image cache, downloader and coder
• High performance

SDWebImage is a powerful library for downloading and caching web images. When BBWebImage first version (0.1.0) is released, the latest version of SDWebImage is 4.4.3 which dose not contain powerful image editing function. If we download an image with SDWebImage 4.4.3 and edit the image, the problems will happen:

1. The edited image is cached, but the original image data is lost. We need to download the original image again if we want to display it.
2. The original image data is cached to disk. If we do not cache the edited image, we need to edit image to display the edited image every time. If we cache the edited image to both memory and disk, we need to write more code and manage the cache key. If we cache the edited image to memory only, when we get the cached image, we need to know whether it is edited by checking where it is cached.
3. If we useCore Graphics to edit image, we should disable SDWebImage image decompressing (because decompressing is unnecessary. Both editing and decompressing have similar steps: createCGContext, draw image, create new image) and enable it later.

BBWebImage is born to solve the problems.

1. The original image data is cached to disk, and the original or edited image is cached to memory. TheUIImage is associated with edit key which is a String identifying how the image is edited. Edit key is nil for original image. When we load image from the network or cache, we can passBBWebImageEditor to get edited image. BBWebImageEditor specifies how to edit image, and contains the edit key which will be associated to the edited image. If the edit key of the memory cached image is the same as the edit key of BBWebImageEditor, then the memory cached image is what we need; Or BBWebImage will load and edit the original image and cache the edited image to memory. If we want the original image, do not pass BBWebImageEditor. We will not download an image more than once. We do not need to write more code to cache edited image or check whether the image is edited.
2. If we load original image, BBWebImage will decompress image by default. If we load image with BBWebImageEditor, BBWebImage will use editor to edit image without decompressing. We do not need to write more code to enable or disable image decompressing.

To display animated image, we need to decode image frames, change frame according to frame duration. We useBBAnimatedImage to manage animated image data, and useBBAnimatedImageView to play the animation. BBAnimatedImageView decides which frame to display or to decode. BBAnimatedImage decodes and caches image frames in the background. The max cache size is calculated dynamically and the cache is cleared automatically.

BBAnimatedImage uses BBWebImageEditor to edit image frames. BBAnimatedImage has a propertybb_editor which is an optional BBWebImageEditor type. Set an editor to the property to display edited image frames, or set nil to display original image frames.

• iOS 8.0+
• Swift 4.2

Install with CocoaPods:

1. Addpod 'BBWebImage' to your Podfile. Addpod 'BBWebImage/MapKit' for MKAnnotationView extension. Addpod 'BBWebImage/Filter' for image filter.
2. Runpod install orpod update.
3. Addimport BBWebImage to the Swift source file.

The simplest way to use is setting image forUIImageView withURL

imageView.bb_setImage(with: url)

The code below:

1. Downloads a high-resolution image
2. Downsamples and crops it to match an expected maximum resolution and image view size
3. Draws it with rounded corner, border and background color
4. Displays edited image after downloading and editing
5. Displays a placeholder image before downloading
6. Decodes image incrementally and displays it while downloading
7. Do something while downloading
8. Caches original image data to disk and caches edited image to memory
9. Do something when loading is finished

leteditor=bb_imageEditorCommon(with: imageView.frame.size,                                  maxResolution:1024*1024,                                  corner:.allCorners,                                  cornerRadius:5,                                  borderWidth:1,                                  borderColor:.yellow,                                  backgroundColor:.gray)letprogress={(data:Data?, expectedSize:Int, image:UIImage?)->Voidin    // Do something while downloading}imageView.bb_setImage(with: url,                      placeholder:UIImage(named:"placeholder"),                      options:.progressiveDownload,                      editor: editor,                      progress: progress){(image:UIImage?, data:Data?, error:Error?, cacheType:BBImageCacheType)in    // Do something when finish loading}

The parameteroptions ofbb_setImage(with:) method isBBWebImageOptions, an option set. Use it to control some behaviors of downloading, caching, decoding and displaying. The value.progressiveDownload means displaying image progressly when downloading. The default value is.none.

The parametereditor ofbb_setImage(with:) method is an optional structBBWebImageEditor. Pass nil to display original image. There are other built-in editors to choose. SeeBuilt-in Image Editors.

To support GIF, replaceUIImageView byBBAnimatedImageView. BBAnimatedImageView is a subclass of UIImageView. BBAnimatedImageView supports both static image and animated image.

To support other image format or change default encode/decode behaivor, seeSupported Image Formats.

To get image from cache or the network without displaying on the view, useBBWebImageManagerloadImage(with:) method. The method returns aBBWebImageLoadTask object. To cancel the task, callcancel() method of the task.

letprogress={(data:Data?, expectedSize:Int, image:UIImage?)->Voidin    // Do something while downloading}BBWebImageManager.shared.loadImage(with: url,                                   options: options,                                   editor: editor,                                   progress: progress){(image:UIImage?, data:Data?, error:Error?, cacheType:BBImageCacheType)in    // Do something when finish loading}

To get image or data from cache, useBBLRUImageCacheimage(forKey:) method. To get image/data from memory/disk only, pass.memory/.disk tocacheType.

BBWebImageManager.shared.imageCache.image(forKey: key,                                          cacheType:.all){(result:BBImageCacheQueryCompletionResult)inswitch result{    caselet.memory(image: image): // Do something with memory image    caselet.disk(data: data): // Do something with disk datacaselet.all(image: image, data: data): // Do something with image and data    default: // Do something when no image or data}}

To store image or data to cache, usestore(_:) method. To store image/data to memory/disk only, pass.memory/.disk tocacheType.

BBWebImageManager.shared.imageCache.store(image,                                          data: data,                                          forKey: key,                                          cacheType:.all){    // Do something after storing}

To remove image or data from cache, useremoveImage(forKey:) method. To remove image/data from memory/disk only, pass.memory/.disk tocacheType.

BBWebImageManager.shared.imageCache.removeImage(forKey: key,                                                cacheType:.all){    // Do something after removing}

To remove all images or data from cache, useclear(_:) method. To remove all image/data from memory/disk only, pass.memory/.disk to first parameter.

BBWebImageManager.shared.imageCache.clear(.all){    // Do something after clearing}

To download image data, useBBMergeRequestImageDownloaderdownload(with:) method. The method returns a task conforming toBBImageDownloadTask protocol. To cancel the task, call downloadercancel(task:) method and pass the task as parameter. To cancel all download tasks, call downloadercancelAll() method.

letprogress={(data:Data?, expectedSize:Int, image:UIImage?)->Voidin    // Do something while downloading}BBWebImageManager.shared.imageDownloader.downloadImage(with: url,                                                       options: options,                                                       progress: progress){(data:Data?, error:Error?)in    // Do something with data or error}

To get decoded image (without decompressing) from data, useBBImageCoderManagerdecodedImage(with:) method. The method returns an optionalUIImage object. If the image isBBAnimatedImage, it is an animated image ready for display onBBAnimatedImageView. If the image is a static image, it is not decompressed. UsedecompressedImage(with: method to decompress it for display.

letcoder=BBWebImageManager.shared.imageCoderiflet decodedImage= coder.decodedImage(with: data){    // Do something with decoded imageiflet animatedImage= decodedImageas?BBAnimatedImage{        // Do something with animated image}elseiflet decompressedImage= coder.decompressedImage(with: decodedImage, data: data){        // Do something with decompressed image}else{        // Can not decompress image}}else{    // Can not decode image data}

To encode image to specific format, useencodedData(with:) method.

iflet data= coder.encodedData(with: image, format:.PNG){    // Do something with data}else{    // Can not encode data}

To support other image format or change default encode/decode behaivor, seeSupported Image Formats.

• JPEG
• PNG
• GIF

To support other image format or change default encode/decode behaivor, customize image coder. Implement new coder conforming toBBImageCoder protocol. Get old coders and change.

iflet coderManager=BBWebImageManager.shared.imageCoderas?BBImageCoderManager{letoldCoders= coderManager.codersletnewCoders=...    coderManager.coders= newCoders}

StructBBWebImageEditor defines how to edit and cache image in memory. The built-in image editors are below:

BBWebImage is released under the MIT license. SeeLICENSE for details.