Awesome
SDWebImagePhotosPlugin
What it's for
SDWebImagePhotosPlugin is a plugin for the SDWebImage framework, which provides image loading support for the Photos Library.
This plugin allows you to use your familiar View Category method from SDWebImage, for loading Photos images with PHAsset
or localIdentifier
.
Requirements
- iOS 9+
- macOS 10.13+
- tvOS 10+
- Xcode 10+
Installation
CocoaPods
SDWebImagePhotosPlugin is available through CocoaPods. To install it, simply add the following line to your Podfile:
pod 'SDWebImagePhotosPlugin'
Carthage
SDWebImagePhotosPlugin is available through Carthage.
github "SDWebImage/SDWebImagePhotosPlugin"
Swift Package Manager (Xcode 11+)
SDWebImagePhotosPlugin is available through Swift Package Manager.
let package = Package(
dependencies: [
.package(url: "https://github.com/SDWebImage/SDWebImagePhotosPlugin.git", from: "1.0")
]
)
Usage
Important! To use this Photos Library plugin, you first need to register the photos loader to image manager.
There are two ways to register the photos loader. One is for temporarily usage (when providing URL is definitely Photos URL but not HTTP URL), and another for global support (don't need any check, supports both HTTP URL as well as Photos URL).
Use custom manager (temporarily)
You can create a custom manager for temporary usage. When you use custom manager, be sure to specify SDWebImageContextCustomManager
context option with your custom manager for View Category methods.
- Objective-C
// Assign loader to custom manager
SDWebImageManager *manager = [[SDWebImageManager alloc] initWithCache:SDImageCache.sharedImageCache loader:SDImagePhotosLoader.sharedLoader];
- Swift
// Assign loader to custom manager
let manager = SDWebImageManager(cache: SDImageCache.shared, loader: SDImagePhotosLoader.shared)
Use loaders manager (globally)
You can replace the default manager's loader implementation using loaders manager to support both HTTP && Photos URL globally. Put these code just at the application launch time (or some time just before SDWebImageManager.sharedManager
is initialized).
- Objective-C
// Supports HTTP URL as well as Photos URL globally
SDImageLoadersManager.sharedManager.loaders = @[SDWebImageDownloader.sharedDownloader, SDImagePhotosLoader.sharedLoader];
// Replace default manager's loader implementation
SDWebImageManager.defaultImageLoader = SDImageLoadersManager.sharedManager;
- Swift
// Supports HTTP URL as well as Photos URL globally
SDImageLoadersManager.shared.loaders = [SDWebImageDownloader.shared, SDImagePhotosLoader.shared]
// Replace default manager's loader implementation
SDWebImageManager.defaultImageLoader = SDImageLoadersManager.shared
Load Images
To start loading the Photos Library image, use the NSURL+SDWebImagePhotosPlugin
to create a Photos URL and call View Category method.
- Objective-C
// Create with `PHAsset`
PHAsset *asset;
NSURL *photosURL = asset.sd_URLRepresentation;
// The same as `[NSURL sd_URLWithAsset:asset];`
// Create with `localIdentifier`
NSString *identifier;
NSURL *potosURL = [NSURL sd_URLWithAssetLocalIdentifier:identifier];
// Load image (assume using custom manager)
[imageView sd_setImageWithURL:photosURL placeholderImage:nil context:@{SDWebImageContextCustomManager: manager}];
- Swift
// Create with `PHAsset`
let asset: PHAsset
let photosURL = asset.sd_URLRepresentation
// The same as `NSURL.sd_URL(with: asset) as URL`
// Create with `localIdentifier`
let identifier: String
let potosURL = NSURL.sd_URL(withAssetLocalIdentifier: identifier) as URL
// Load image (assume using custom manager)
imageView.sd_setImage(with: photosURL, placeholderImage: nil, context: [.customManager: manager])
Animated Images
SDWebImagePhotosPlugin supports GIF images stored in Photos Library as well. Just use the same API as normal images to query the asset. We will query the image data and decode the animated images (compatible with UIImageView
as well as SDAnimatedImageView)
Video Assets
SDWebImagePhotosPlugin supports loading Video Asset poster as well. By default, we don't allow non-image type assets, to avoid accidentally picking a wrong Asset. But you can disable this limit as well.
- Objective-C
SDImagePhotosLoader.sharedLoader.requestImageAssetOnly = NO;
- Swift
SDImagePhotosLoader.shared.requestImageAssetOnly = false
Then just request the PHAssets or using the fetch options, which the media type is .video
.
Fetch/Request Options
To specify options like PHFetchOptions
or PHImageRequestOptions
for Photos Library. Either to change the correspond properties in loader, or provide a context options for each image request.
- Objective-C
// loader-level options
// ignore iCloud Shared Album (`localIdentifier` Photos URL only)
PHFetchOptions *fetchOptions = [PHFetchOptions new];
fetchOptions.predicate = [NSPredicate predicateWithFormat:@"sourceType != %d", PHAssetSourceTypeCloudShared];
SDImagePhotosLoader.sharedLoader.fetchOptions = fetchOptions;
// request-level options
// allows iCloud Photos Library
PHImageRequestOptions *requestOptions = [PHImageRequestOptions new];
requestOptions.networkAccessAllowed = YES;
[imageView sd_setImageWithURL:photosURL placeholderImage:nil context:@{SDWebImageContextPhotosImageRequestOptions: requestOptions, SDWebImageContextCustomManager: manager}];
- Swift
// loader-level options
// ignore iCloud Shared Album (`localIdentifier` Photos URL only)
let fetchOptions = PHFetchOptions()
fetchOptions.predicate = NSPredicate(format: "sourceType != %d", PHAssetSourceType.typeCloudShared.rawValue)
SDImagePhotosLoader.shared.fetchOptions = fetchOptions
// request-level options
// allows iCloud Photos Library
let requestOptions = PHImageRequestOptions()
requestOptions.networkAccessAllowed = true
imageView.sd_setImage(with: photosURL, placeholderImage: nil, context:[.photosImageRequestOptions: requestOptions, .customManager: manager])
Control Query Image Size
Photos taken by the iPhone camera may have a really large pixel size (4K+). So, if you want to load large Photos Library assets for rendering, you should specify target size with a limited size (for example, the size of the imageView that you are loading into).
By default, we query the target size that matches the original image's largest size (see: PHImageManagerMaximumSize), which may consume too much memory on iOS devices. There are also two built-in dynamic values SDWebImagePhotosPixelSize/SDWebImagePhotosPointSize
which are suitable for some cases.
You can change the fetch image size by either using the PHImageRequestOptions.sd_targetSize
, or Thumbnail Decoding via .imageThumbnailPixelSize
context option.
Control query image size limit in global:
- Objective-C
SDImagePhotosLoader.sharedLoader.imageRequestOptions.sd_targetSize = CGSizeMake(1000, 1000); // Limit 1000x1000 pixels
- Swift
SDImagePhotosLoader.shared.imageRequestOptions.sd_targetSize = CGSize(width: 1000, height: 1000) // Limit 1000x1000 pixels
Control query image size for individual assets:
- Objective-C
UIImageView *imageView;
PHAsset *asset;
NSURL *url = asset.sd_URLRepresentation;
[imageView.sd_setImageWithURL:url options:0 context:@{SDWebImageContextImageThumbnailPixelSize: @(imageView.bounds.size)}]; // Fetch image based on image view size
- Swift
let imageView: UIImageView
let asset: PHAsset
let url = asset.sd_URLRepresentation
imageView.sd_setImage(with: url, context: [.imageThumbnailPixelSize : imageView.bounds.size]) // Fetch image based on image view size
Note: You can also use SDWebImageContextPhotosImageRequestOptions
as shown above. But the thumbnail pixel size can be used for normal Network URL as well, which can help you to unify the logic for HTTP URL and PHAsset URL.
Tips
- Images from the Photos Library are already stored on the device disk, and query speed is fast enough for small resolution images, so cache storage might be unnecessary. You can use
SDWebImageContextStoreCacheType
withSDImageCacheTypeNone
to disable cache storage, and useSDWebImageFromLoaderOnly
to disable cache queries. - If you use
PHImageRequestOptionsDeliveryModeOpportunistic
(default) to load the image, PhotosKit will return a degraded thumbnail image first and again with the full pixel image. When the image is degraded, the loader completion block will setfinished = NO
. However, this will not trigger the View Category completion block, and only trigger a image refresh (like progressive loading behavior for network image usingSDWebImageProgressiveLoad
) - By default, we will prefer using Photos requestImageForAsset:targetSize:contentMode:options:resultHandler: API for normal images, using requestImageDataForAsset:options:resultHandler: for animated images like GIF asset. If you need the raw image data for further image processing, you can always pass the
SDWebImageContextPhotosRequestImageData
context option to force using the request data API instead. Note that when requesting data, thetargetSize
andcontentMode
options are ignored. If you need smaller image sizes, consider using Image Transformer feature from SDWebImage 5.0.
Demo
If you have some issue about usage, SDWebImagePhotosPlugin provide a demo for iOS & macOS platform. To run the demo, clone the repo and run the following command.
cd Example/
pod install
open SDWebImagePhotosPlugin.xcworkspace
After the Xcode project is opened, click <kbd>Run</kbd> to build and run the demo.
Author
DreamPiggy, lizhuoli1126@126.com
License
SDWebImagePhotosPlugin is available under the MIT license. See the LICENSE file for more info.