5.0 Migration guide
SDWebImage 5.0 is the latest major release of SDWebImage, a top library for downloading and caching images. As a major release, following Semantic Versioning conventions, 5.0 introduces several API-breaking changes with its new architecture.
This guide is provided in order to ease the transition of existing applications using SDWebImage 4.X to the latest APIs, as well as explain the design and structure of new and changed functionality.
SDWebImage 5.0 officially supports iOS 8 and later, Mac OS X 10.10 and later, watchOS 2 and later and tvOS 9 and later. It needs Xcode 9 or later to be able to build everything properly.
For targeting previous versions of the SDKs, check README - Backwards compatibility.
Using the view categories brings no change from 4.x to 5.0.
Objective-C:
[imageView sd_setImageWithURL:url placeholderImage:placeholderImage];
Swift:
imageView.sd_setImage(with: url, placeholderImage: placeholder)
However, all view categories in 5.0 introduce a new extra arg called SDWebImageContext
. This param can hold anything, as opposed to the previous SDWebImageOptions
enum limitations. This gives developers advanced control for the behavior of image loading (cache, loader, etc). See the declaration for SDWebImageContext
for detailed information.
In 5.0, we introduced a brand new mechanism for supporting animated images. This includes animated image loading, rendering, decoding, and also supports customizations (for advanced users).
This animated image solution is available for iOS
/tvOS
/macOS
. The SDAnimatedImage
is subclass of UIImage/NSImage
, and SDAnimatedImageView
is subclass of UIImageView/NSImageView
, to make them compatible with the common frameworks APIs. See Animated Image for more detailed information.
In 5.0, we introduced an easy way to hook an image transformation process after the image was downloaded from network. This allows the user to easily scale, rotate, add rounded corner the original image and even chain a list of transformations. These transformed images will also be stored to the cache as they are after transformation. The reasons for this decision are: avoiding redoing the transformations (which can lead to unwanted behavior) and also time saving. See Image Transformer for more detailed information.
In 5.0, we refactored our framework architecture in many aspects. This makes our framework easier to customize for advanced users, without the need for hooking anything or forking. We introduced Custom Cache to control detailed cache loading behavior, and separate the memory cache & disk cache implementation. We introduced Custom Loader to allow custom loading from your own source (doesn't have to be the network). And also, we changed the current Custom Coder to work better for custom image decoder/encoder and animated images.
In 5.0, we refactored the image loading indicator API into a better and extensible API for iOS
/tvOS
/macOS
. This is suitable for easy usage like providing a loading view during the image loading process. See View Indicator for more detailed information.
In order to clean up things and make our core project do less things, we decided that the FLAnimatedImage
integration does not belong here. From 5.0, this will still be available, but under a dedicated repo SDWebImageFLPlugin.
By taking the advantage of the Custom Loader feature, we introduced a plugin to allow easy loading images from the Photos Library. See SDWebImagePhotosPlugin for more detailed information.
SDImageCache
in 5.x, use ~/Library/Caches/com.hackemist.SDImageCache/default/
as default cache path. However, 4.x use ~/Library/Caches/default/com.hackemist.SDWebImageCache.default/
. And don't be worried, we will do the migration automatically once the shared cache initialized.
However, if you have some other custom namespace cache instance, you should try to do migration by yourself. But typically, since the cache is designed to be invalid at any time, you'd better not to bind some important logic related on that cache path changes.
And, if you're previously using any version from 5.0.0-beta
to 5.0.0-beta3
, please note that the cache folder has been temporarily moved to ~/Library/Caches/default/com.hackemist.SDImageCache.default/
, however, the final release version of 5.0.0 use the path above. If you upgrade from those beta version, you may need manually do migration, check +[SDDiskCache moveCacheDirectoryFromPath:toPath:]
for detail information.
SDImageCacheConfig.maxMemoryCost
can be used to specify the memory cost limit. In the 4.x, the cost function is the pixel count of images. However, 5.x change it into the total bytes size of images.
Because for memory cache, we actually care about the memory usage about bytes, but not the count of pixels. And pixel count can not accurately represent the memory usage.
The bytes of a image occupied in the memory, can use the simple formula below:
bytes size = pixel count * bytes per pixel
The bytes per pixel is a constant depends on image pixel format. For mostly used images (8 bits per channel with alpha), the value is 4. So you can simply migrate your previous pixel count value with 4 multiplied.
SDWebImagePrefetcher
in 5.x, change the concept of fetching batch of URLs. Now, each time you call prefetchURLs:
, you will get a token which represents the specified URLs list. It does not cancel the previous URLs which is prefetching, which make the shared prefetcher behaves more intuitively.
However, in 4.x, each time you call prefetchURLs:
, it will cancel all previous URLs which is been prefetching.
If you still want the same behavior, manually call cancelPrefetching
each time before any prefetchURLs:
calls.
- Objective-C
SDWebImagePrefetcher *prefetcher = SDWebImagePrefetcher.sharedImagePrefetcher;
[prefetcher cancelPrefetching];
[prefetcher prefetchURLs:@[url1, url2]];
- Swift
let prefetcher = SDWebImagePrefetcher.shared
prefetcher.cancelPrefetching()
prefetcher.prefetchURLs([url1, url2])
For image loading from network, if you don't pass SDWebImageRetryFailed
option, we'll try to blocking some URLs which is indeed mark as failed.
This check is done previously in a hard-coded logic for specify error codes. However, due to some compatible issue, we don't check the error domain. (Learn about NSError's domain and codes) And arbitrarily block some codes which may from custom download operation implementations.
Since in 5.x, we supports custom loaders which can use any third-party SDKs, and have their own error domain and error codes. So we now only filter the error codes in NSURLErrorDomain. If you have already using some error codes without error domain check, or you use Custom Download Operation, be sure to update it with the right way.
At the same time, our framework errors, now using the formal SDWebImageErrorDomain
with the pre-defined codes. Check SDWebImageError.h
for details.
- moved
maxMemoryCost
andmaxMemoryCountLimit
toSDImageCacheConfig
-
makeDiskCachePath:
removed, useNSSearchPathForDirectoriesInDomains
with NSString's Path API instead. -
addReadOnlyCachePath:
removed, useadditionalCachePathBlock
instead -
cachePathForKey:inPath:
removed, usecachePathForKey:
with NSString's path API instead. -
defaultCachePathForKey:
removed, usecachePathForKey:
instead -
SDCacheQueryCompletedBlock
renamed toSDImageCacheQueryCompletionBlock
-
SDWebImageCheckCacheCompletionBlock
renamed toSDImageCacheCheckCompletionBlock
-
SDWebImageCalculateSizeBlock
renamed toSDImageCacheCalculateSizeBlock
-
getSize
renamed tototalDiskSize
-
getDiskCount
renamed tototalDiskCount
-
shouldDecompressImages
removed. UseSDImageCacheAvoidDecodeImage
in cache options instead -
maxCacheAge
renamed tomaxDiskAge
-
maxCacheSize
renamed tomaxDiskSize
-
loadImageWithURL:options:progress:completed:
changed thecompleted
param requirement fromnullable
tononnull
-
loadImageWithURL:options:progress:completed:
return typeid<SDWebImageOperation>
changed toSDWebImageCombinedOperation *
-
imageCache
changed from nullable to nonnull. And property type changed fromSDImageCache *
toid<SDImageCache>
. The default value does not change. -
imageDownloader
renamed toimageLoader
and changed from nullable to nonnull. And property type changed fromSDWebImageDownloader *
toid<SDImageLoader>
. The default value does not change. -
cacheKeyFilter
property type changed toid<SDWebImageCacheKeyFilter>
, you can use+[SDWebImageCacheKeyFilter cacheKeyFilterWithBlock:]
to create -
cacheSerializer
property type changed toid<SDWebImageCacheSerializer>
, you can use+[SDWebImageCacheSerializer cacheSerializerWithBlock:]
to create -
SDWebImageCacheKeyFilterBlock
'surl
arg change from nullable to nonnull -
initWithCache:downloader:
'scache
arg type changed fromSDImageCache *
toid<SDImageCache>
-
initWithCache:downloader
renamed toinitWithCache:loader:
-
saveImageToCache:forURL:
removed. UseSDImageCache storeImage:imageData:forKey:cacheType:completion:
(orSDImageCache storeImage:forKey:toDisk:completion:
if you use default cache class) withcacheKeyForURL:
instead. -
diskImageExistsForURL:completion:
removed. UseSDImageCache containsImageForKey:cacheType:completion:
(orSDImageCache diskImageExistsWithKey:completion:
if you use default cache class) withcacheKeyForURL:
instead. -
cachedImageExistsForURL:completion
removed. UseSDImageCache containsImageForKey:cacheType:completion:
(orSDImageCache diskImageExistsWithKey:completion:
andSDImageCache imageFromMemoryCacheForKey:
if you use default cache class) withcacheKeyForURL:
instead.
- removed
imageManager:transformDownloadedImage:forKey:
, useSDImageTransformer
with context option instead
-
sd_internalSetImageWithURL:placeholderImage:options:operationKey:setImageBlock:progress:completed:
renamed toUIView sd_internalSetImageWithURL:placeholderImage:options:context:setImageBlock:progress:completed:
(The biggest changes is that the completion block type fromSDExternalCompletionBlock
toSDInternalCompletionBlock
. Which allow advanced user to get more information of image loading process) -
sd_internalSetImageWithURL:placeholderImage:options:operationKey:setImageBlock:progress:completed:context:
removed - activity indicator refactoring - use
sd_imageIndicator
withSDWebImageActivityIndicator
-
sd_setShowActivityIndicatorView:
removed -
sd_setIndicatorStyle:
removed -
sd_showActivityIndicatorView
removed -
sd_addActivityIndicator:
removed -
sd_removeActivityIndicator:
removed
-
- Renamed
isGIF
tosd_isAnimated
, alsoNSImage isGIF
renamed toNSImage sd_isAnimated
- Renamed
decodedImageWithImage:
tosd_decodedImageWithImage:
- Renamed
decodedAndScaledDownImageWithImage:
tosd_decodedAndScaledDownImageWithImage:
- Renamed
sd_animatedGIFWithData
tosd_imageWithGIFData:
- Removed
sd_webpLoopCount
- Removed
sd_setImageWithPreviousCachedImageWithURL:placeholderImage:options:progress:completed
- Removed
sd_setAnimationImagesWithURLs:
. You can useSDWebImagePrefetcher
with memory cache to grab the batch loaded images - Removed
sd_cancelCurrentAnimationImagesLoad
. You can useSDWebImagePrefetcher
with token cancel the batch loading images
-
shouldDecompressImages
moved toSDWebImageDownloaderConfig.shouldDecompressImages
-
maxConcurrentDownloads
moved toSDWebImageDownloaderConfig.maxConcurrentDownloads
-
downloadTimeout
moved toSDWebImageDownloaderConfig.downloadTimeout
-
operationClass
moved toSDWebImageDownloaderConfig.operationClass
-
executionOrder
moved toSDWebImageDownloaderConfig.executionOrder
-
urlCredential
moved toSDWebImageDownloaderConfig.urlCredential
-
username
moved toSDWebImageDownloaderConfig.username
-
password
moved toSDWebImageDownloaderConfig.password
-
initWithSessionConfiguration:
removed, useinitWithConfig:
with session configuration instead -
createNewSessionWithConfiguration:
removed, useinitWithConfig:
with new session configuration instead. To modify shared downloader configuration, provide customSDWebImageDownloaderConfig.defaultDownloaderConfig
before it created. -
headersFilter
removed, userequestModifier
instead -
cancel:
removed, use-[SDWebImageDownloadToken cancel]
instead -
shouldDecompressImages
removed. UseSDWebImageDownloaderAvoidDecodeImage
in downloader options instead - use
SDImageLoaderProgressBlock
instead ofSDWebImageDownloaderProgressBlock
- use
SDImageLoaderCompletedBlock
instead ofSDWebImageDownloaderCompletedBlock
-
initWithRequest:inSession:options:context:
is now the designated initializer - Removed
shouldUseCredentialStorage
property -
SDWebImageDownloadOperationInterface
protocol renamed toSDWebImageDownloadOperation
-
expectedSize
removed, useresponse.expectedContentLength
instead -
shouldDecompressImages
removed. UseSDWebImageDownloaderAvoidDecodeImage
in downloader options instead. -
response
property change to readonly
-
prefetchURLs:
andprefetchURLs:progress:completed:
return types changed fromvoid
toSDWebImagePrefetchToken
-
prefetcherQueue
property renamed todelegateQueue
-
maxConcurrentDownloads
replaced withmaxConcurrentPrefetchCount
-
SDCGColorSpaceGetDeviceRGB()
moved to+[SDImageCoderHelper colorSpaceGetDeviceRGB]
-
SDCGImageRefContainsAlpha()
, moved to+[SDImageCoderHelper imageRefContainsAlpha:]
-
decodedImageWithData:
replaced withdecodedImageWithData:options:
-
encodedDataWithImage:format:
replaced withencodedDataWithImage:format:options
-
init
method fromSDWebImageProgressiveCoder
changed toinitIncrementalWithOptions:
-
incrementalDecodedImageWithData:finished
replaced withupdateIncrementalData:finished
andincrementalDecodedImageWithOptions:
two APIs - removed
decompressedImage:data:options
, use+[SDImageCoderHelper decodedImageWithImage:]
and+[SDImageCoderHelper decodedAndScaledDownImageWithImage:limitBytes:]
instead
-
SDWebImageProgressiveDownload
renamed toSDWebImageProgressiveLoad
-
SDWebImageCacheMemoryOnly
removed, use@{SDWebImageContextStoreCacheType : @(SDImageCacheTypeMemory)}
context option instead. For Swift user, using[.storeCacheType: SDImageCacheType.memory.rawValue]
(rawValue
is important, same for other scalar type context option). -
SDWebImageQueryDiskSync
removed. UseSDWebImageQueryDiskDataSync
instead. -
SDWebImageQueryDataWhenInMemory
removed. UseSDWebImageQueryMemoryData
instead. If you want to query memory data sync as well, combined withSDWebImageQueryMemoryDataSync
-
SDWebImageInternalSetImageGroupKey
removed -
SDWebImageExternalCustomManagerKey
renamed toSDWebImageContextCustomManager
In SDWebImage 5.0 we did a clean up of the API. We are using many modern Objective-C declarations to generate the Swift API. We now provide full nullability support, string enum, class property, and even custom Swift API name, all to make the framework easier to use for our Swift users. Here are the API change specify for Swift.
-
sd_imageURL()
changed tosd_imageURL
-
shared()
changed toshared
-
shared()
changed toshared
-
isRunning()
changed toisRunning
-
shared()
changed toshared
-
setOperationClass(_:)
available for Swift user withoperationClass
property -
setSuspended(_:)
changed toisSuspended
property
-
SDWebImageDownloadOperationInterface
protocol renamed toSDWebImageDownloadOperationProtocol
.
-
sharedInstance()
changed toshared
-
shared()
changed toshared
-
shared()
changed toshared
-
shared()
changed toshared
-
sd_UTTypeFromSDImageFormat
returnCFString
instead ofUnmanaged<CFString>
-
sd_currentImageURL()
changed tosd_currentImageURL
-
sd_currentImageURL()
changed tosd_currentImageURL
-
sd_currentAlternateImageURL()
changed tosd_currentAlternateImageURL
For advanced user who need the detailed API diff, we provide the full diff in a HTML web page (based on 4.4.6 and 5.0.0):