SDWebImagePhotosPlugin 1.2.0

SDWebImagePhotosPlugin 1.2.0

×

由 DreamPiggy 和 Bogdan Poplauschi 维护。

SDWebImagePhotosPlugin 1.2.0

  • 由
  • DreamPiggy

SDWebImagePhotosPlugin

CI Status Version License Platform Carthage compatible SwiftPM compatible codecov

用途

SDWebImagePhotosPlugin 是 SDWebImage 框架的一个插件，该框架为 SDWebImage 提供图片加载支持，用于 Photos Library。

此插件允许您使用 SDWebImage 的熟悉视图分类方法，使用 PHAsset 或 localIdentifier 加载 Photos 图像。

要求

  • iOS 9+
  • macOS 10.13+
  • tvOS 10+
  • Xcode 10+

安装

CocoaPods

SDWebImagePhotosPlugin 可以通过 CocoaPods 获取。要安装它，只需将以下行添加到您的 Podfile 中。

pod 'SDWebImagePhotosPlugin'

Carthage

SDWebImagePhotosPlugin 可以通过 Carthage 获取。

github "SDWebImage/SDWebImagePhotosPlugin"

Swift Package Manager (Xcode 11+)

SDWebImagePhotosPlugin 可以通过 Swift Package Manager 获取。

let package = Package(
    dependencies: [
        .package(url: "https://github.com/SDWebImage/SDWebImagePhotosPlugin.git", from: "1.0")
    ]
)

使用方法

重要！ 使用此 Photos Library 插件之前，您首先需要将照片加载器注册到图像管理器中。

注册照片加载器有两种方式。一种用于临时使用（当提供的 URL 一定是 Photos URL 但不是 HTTP URL 的情况），另一种用于全局支持（无需任何检查，支持 HTTP URL 和 Photos URL）。

使用自定义管理器（临时使用）

您可以为临时使用创建一个自定义管理器。当您使用自定义管理器时，务必为 View Category 方法指定 SDWebImageContextCustomManager 上下文选项和您的自定义管理器。

  • 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)

使用加载器管理器（全局使用）

您可以使用加载器管理器通过 加载器管理器 替换默认管理器的加载器实现，以支持全局的 HTTP && Photos URL。请在应用程序启动时（或在初始化 SDWebImageManager.sharedManager 之前的一些时间）添加这些代码。

  • 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

加载图片

要开始加载相册的图片，使用 NSURL+SDWebImagePhotosPlugin 创建相册URL并调用视图分类方法。

  • 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])

动画图片

SDWebImagePhotosPlugin 也支持加载存储在相册中的 GIF 图片。只需使用与普通图片相同的 API 来查询资产。我们将查询图像数据并解码动画图片（兼容 UIImageView 以及 SDAnimatedImageView）

视频资源

SDWebImagePhotosPlugin 也支持加载视频资源海报。默认情况下，我们不允许非图像类型资源，以避免意外选择错误的资源。但您可以禁用此限制。

  • Objective-C
SDImagePhotosLoader.sharedLoader.requestImageAssetOnly = NO;
  • Swift
SDImagePhotosLoader.shared.requestImageAssetOnly = false

然后，只需请求 PHAssets 或使用请求选项，其中媒体类型是 .video。

检索/请求选项

为相册指定选项，如 PHFetchOptions 或 PHImageRequestOptions。要么更改加载器中的相应属性，要么为每个图像请求提供上下文选项。

  • 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])

控制查询图像大小

使用iPhone摄像头拍摄的照片可能有非常大的像素尺寸（4K+）。因此，如果您想要加载数较大的照片库资源进行渲染，应指定有限大小的目标尺寸（例如，您要加载到imageView中的尺寸）。

默认情况下，我们会查询匹配原始图像最大尺寸的目标尺寸（请参阅：PHImageManagerMaximumSize），这可能会在iOS设备上消耗过多内存。此外，还有两个内置的动态值 SDWebImagePhotosPixelSize/SDWebImagePhotosPointSize，适用于某些情况。

您可以通过使用PHImageRequestOptions.sd_targetSize或通过.imageThumbnailPixelSize上下文选项通过缩略图解码来更改获取图像的大小。

在全局中控制查询图像尺寸限制

  • 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

控制单个资源的图像尺寸查询

  • 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

注意：您也可以像上面那样使用SDWebImageContextPhotosImageRequestOptions。但是，缩略图像素大小也可以用于正常的网络URL，这可以帮助您统一HTTP URL和PHAsset URL的逻辑。

提示

  1. 照片库中的图片已经存储在设备磁盘上，对于小分辨率图片，查询速度足够快，因此缓存存储可能是不必要的。您可以使用SDWebImageContextStoreCacheType与SDImageCacheTypeNone来禁用缓存存储，使用SDWebImageFromLoaderOnly来禁用缓存查询。
  2. 如果您使用PHImageRequestOptionsDeliveryModeOpportunistic（默认）加载图像，PhotosKit将首先返回一个降级缩略图图像，然后再次与完整像素图像。当图像降级时，加载器完成块将设置finished = NO。然而，这不会触发视图类别完成块，只会触发图像刷新（例如，像使用SDWebImageProgressiveLoad进行网络图像的渐进式加载行为）。
  3. 默认情况下，我们会优先使用Photos的requestImageForAsset:targetSize:contentMode:options:resultHandler: API处理常见图像，使用requestImageDataForAsset:options:resultHandler:处理如GIF资源这样的动态图像。如果您需要进一步图像处理的原始图像数据，您始终可以通过传递SDWebImageContextPhotosRequestImageData上下文选项来强制使用请求数据API。请注意，当请求数据时， Ignore the targetSize and contentMode options. 如果您需要更小的图像尺寸，请考虑使用从SDWebImage 5.0开始提供的Image Transformer功能。

示例

如果您在使用过程中遇到问题，SDWebImagePhotosPlugin为iOS和macOS平台提供了一个示例。要运行示例，克隆存储库并执行以下命令。

cd Example/
pod install
open SDWebImagePhotosPlugin.xcworkspace

打开Xcode项目后，单击运行以构建和运行示例。

作者

DreamPiggy, [email protected]

许可协议

SDWebImagePhotosPlugin遵循MIT许可协议。有关更多信息，请参阅LICENSE文件。