功能接入

本文档将为您介绍 iOS 加载 SDK 的支持能力和具体接入说明。

渐进式图片加载

当处于以下场景时，您可选择渐进式图片加载提升加载体验：图片（体积）较大、弱网环境、内存紧张。SDK 支持动图和静图的渐进式图片加载，支持图片格式如下所示：

• 动图：gif、avif、heif、awebp

• 静图： jpeg、png、heic

//图片 URL
NSURL *url = [NSURL URLWithString:@"https://xxx.xxx"];

//只针对动图，类似 chrome 浏览器播放动图的效果，会一边下载一边播放已经下载好的帧
[imageView bd_setImageWithURL:url options:BDImageAnimatedImageProgressiveDownload];

//只针对静图（jpeg，png）进行边下边渲染
[imageView bd_setImageWithURL:url options:BDImageStaticImageProgressiveDownload];

//如果 HEIC 图片内包含缩略图，先加载 HEIC 图片的缩略图。接入该功能需要特定的 veImageX URL 模版，需要您在 veImageX 控制台进行配置
[imageView bd_setImageWithURL:url options:BDImageHeicProgressDownloadForThumbnail];

//HEIC 图片缩略图会返回 SDK 的上层 ( 意味着有两次 completeBlock 回调，缩略图+原图）
[imageView bd_setImageWithURL:url options:BDImageHeicThumbnailPassToBusinessLayer];

备选 URL

如果遇到超时、DNS 解析失败、连接主机失败等原因，SDK 会触发备选 URL 逻辑，默认按照数组顺序重试，直到所有 URL 失败才会返回错误。

[imageView bd_setImageWithURL:[NSURL urlWithString:@"http://xxx.xxx"]
              alternativeURLs:@[[NSURL urlWithString:@"http://xxx.xxx"]]//备选 URL，暂无限制
                  placeholder:nil
                      options:BDImageRequestDefaultOptions
                       config:config
                       blocks:nil];

重试次数

如果遇到超时、NDS 解析失败、连接主机失败等原因，SDK 会触发重试逻辑，超过重试次数后返回结果。

[BDWebImageManager sharedManager].maxRetryCount = 3; // 设置最大重试次数为3

若在下载时指定 BDImageNoRetry选项，下载失败将不会重试。

图片处理

SDK 支持对加载后图片进行图片处理，支持功能有：图片圆角设置、纯色图片绘制、裁剪等。具体功能和代码示例如下所示：

//BDWebImage 已经预置了一些常用 transformer，比如加圆角
BDRoundCornerTransformer *transformer = [BDRoundCornerTransformer defaultTransformer];
    [imageView bd_setImageWithURL:url placeholder:nil options:BDImageProgressiveDownload transformer:transformer progress:^(BDWebImageRequest *request, NSInteger receivedSize, NSInteger expectedSize) {
        progress = (float)receivedSize / expectedSize;
} completion:^(BDWebImageRequest *request, UIImage *image, NSData *data, NSError *error, BDWebImageResultFrom from) {
    if (from == BDWebImageResultFromDiskCache) {
        NSLog(@"load from disk cache");
    }
}];

BDWebImage中还提供了图片基础变换的子库，代码示例如下所示：

// 绘制纯色图片
image = [UIImage bd_imageWithColor:[UIColor redColor]];
     
// resize（downsample）
image = [image bd_imageByResizeToSize:CGSizeMake(10, 20) contentMode:UIViewContentModeLeft];
     
// 裁剪
image = [image bd_imageByCropToRect:CGRectMake(10, 10, 50, 50)];
 
// insert edge
image = [image bd_imageByInsetEdge:UIEdgeInsetsMake(10, 40, 10, 10) withColor:[UIColor redColor]];
 
// 旋转
image = [image bd_imageByRotateLeft90];
 
// 翻转
image = [image bd_imageByFlipVertical];
 
// 颜色填充（纯色）
image = [image bd_imageByTintColor:[UIColor redColor]];
 
// 灰度化
image = [image bd_imageByGrayscale];
 
// 滤波
image = [image bd_imageByBlurExtraLight];

// 圆角
image = [image bd_imageByRoundCornerRadius:image.size.width/10];

图片缓存

您可根据实际业务设置自己的缓存策略，否则若使用默认缓存策略则实际性能表现可能会有较大差异。

BDImageCacheConfig *cacheConfig = [[BDImageCacheConfig alloc] init];
cacheConfig.clearMemoryOnMemoryWarning = YES; //收到 memory warning 的时候清空内存缓存
cacheConfig.clearMemoryWhenEnteringBackground = YES; //应用进入后台清空内存缓存
cacheConfig.memoryCountLimit = NSUIntegerMax;    //内存缓存数量限制，默认无限制
cacheConfig.memorySizeLimit = NSUIntegerMax; //内存缓存大小限制，默认无限制。单位 byte
cacheConfig.memoryAgeLimit = 12 * 60 * 60; //内存缓存存活时长 12 小时
cacheConfig.trimDiskWhenEnteringBackground = YES;//应用进入后台时清理超限或过期的磁盘缓存
cacheConfig.diskCountLimit = NSUIntegerMax;    //磁盘缓存对象个数
cacheConfig.diskSizeLimit = 256 * 1024 * 1024; //磁盘缓存大小限制 256 M
cacheConfig.diskAgeLimit = 7 * 24 * 60 * 60; //磁盘缓存最大时长 7 天
cacheConfig.singleImageMemorySizeLimit =  1 * 1024 * 1024; //单张图片（对于动图，只算第一帧）进缓存的最大内存缓存大小（字节数，Attention，单位 byte）限制，即超过该大小的图片不会储存到内存缓存，默认无限制
cacheConfig.enableLRU = YES; //LRU 启用
[BDImageCache sharedImageCache].config = cacheConfig;
BDImageCache *cache = [BDImageCache sharedImageCache];
cache.totalDiskSize;//同步获取磁盘缓存的所有数据的字节数
[cache trimDiskCache];//同步根据设置的最大磁盘大小，对象数量和过期时间，清除过期的缓存
[cache clearMemory];//清除内存缓存中的所有数据
[cache clearDiskWithBlock:^{ // 清除磁盘缓存中的所有数据，回调在 BDDiskCache内部的子线程上NSLog(@"disk cleared"); 
}];

图片预加载

在未访问图片前提前下载图片到本地，若请求遇到相同的资源 URL 路径时，SDK 会优先从缓存中获取。预加载加载速度快，可以提升您的加载体验。具体代码示例如下所示：

NSURL *url = [NSURL URLWithString:@"http:xxx.xxx"];
[[BDWebImageManager sharedManager] prefetchImageWithURL:url category:nil  options:BDImageRequestDefaultOptions];

查看已加载图片格式

代码示例如下所示：

// BDImage.h
@property (nonatomic, readonly)BDImageCodeType codeType;//原始数据编码格式

URL 映射

同一个文件的不同 URL 共用一份缓存，BDWebImageManager 支持设置URLFilter - (NSString *)identifierWithURL:(NSURL *)url; 实现此方法后 manager 内部调度会根据具体的 URL-key 计算策略来唯一标识一个图片请求。

您可在以下场景使用 URL 映射功能：

• 多 CDN 域名映射为同一个图片，适用于内部缓存和下载策略去重场景。

• 图片后缀兼容，如多处访问同一个图片但是使用不同格式，即下载 webp 图片后可以不用下载 jpg 版本。

• 需要多图片尺寸大小支持，如适配不同图片展示窗口。

// 您可以继承BDWebImageURLFilter类, 重写- (NSString \*)identifierWithURL:(NSURL \*)url;实现自己的 hash 让同一张图片的不同 url 的 hash 结果相等。
// 实现自定义filter类
@interface CustomFilter : BDWebImageURLFilter

@end

@implementation CustomFilter

- (NSString * _Nonnull)identifierWithURL:(NSURL * _Nonnull)url {
    // 实现相关业务逻辑
    return @"";
}

@end

// 设置自定义filter
CustomFilter *customFilter = [CustomFilter new];
[BDWebImageManager sharedManager].urlFilter = customFilter;

跳过解码过程

如果您需要跳过解码过程，节省加载性能，您可以在下载图片到本地磁盘后填写磁盘路径，并在调用时增加BDImageRequestIgnoreImage和BDImageRequestNeedCachePath选项。

[self bd_setImageWithURL:[NSURL URLWithString:@"http://xxx.xxx"]
             placeholder:nil
                 options:BDImageRequestDefaultOptions | BDImageRequestIgnoreImage | BDImageRequestNeedCachePath 
               cacheName:nil
                progress:nil
              completion:nil];

缓存控制

如果您需要对图片库的缓存做额外的定制，您可以注册新的缓存管理实例，控制图片缓存大小，通过自定义BDImageCacheConfig中各项参数，平衡内存占用和 CPU 占用。

// 创建 cache
BDImageCache *cache = [[BDImageCache alloc] initWithName:@"pathName"];

// 设置 config
BDImageCacheConfig *config = [[BDImageCacheConfig alloc] init];
config.clearMemoryOnMemoryWarning = YES; // 在低内存清空缓存
config.memoryCountLimit = 30;            // 最大内存缓存个数
config.diskAgeLimit = 25200;             // 磁盘缓存时间，单位为秒
...
cache.config = config;

// 注册缓存
[BDWebImageManager.sharedManager registCache:cache forKey:@"cacheName"];

/* 
	请求图片时刻传入 cacheName
   BDWebImageManager 的 insulatedCache 属性控制在查询图片缓存的时刻，是否只查询注册为 cacheName 名称的缓存   
   1. 如果当前开启 insulatedCache 选项，并且当前图片请求的 cacheName 不为 nil，那么只会向注册为 cacheName 名字的缓存管理 BDImageCache 中查找图片缓存，如果没有找到图片缓存那么默认无法找到图片缓存，不继续查找   
   2. 否则会向所有的缓存管理 BDImageCache 中查找该图片缓存，不受 cacheName 限制
*/
[self bd_setImageWithURL:[NSURL URLWithString:@"http://xxx.xxx"]
             placeholder:nil
                 options:BDImageRequestDefaultOptions
               cacheName:@"xxx"
                progress:nil
              completion:nil];

预解码

预解码可以提升图像第一次渲染到屏幕时的性能和滚动帧率，但会增加内存压力，推荐在大量小图渲染场景开启。
在发送请求时，支持以下两种方式开启预解码：

• 方式 1： 通过使用BDImageNotDecoderForDisplay指定是否开启Force Redraw解码。
• 方式 2： 通过使用isDecoderForDisplay来统一开关，默认开启Force Redraw解码。

自动缩小

下载图片时，您可以通过使用BDImageScaleDownLargeImages来自动缩小图片。如果图片生成的CGImage 大于 60 M，则会把图片的长宽做等比例缩小，直至缩小到CGImage为 60 M。该功能生效前提是Force Redraw （预解码）为开启状态。

如果发生缩小操作，下载回调中的 image 为缩小后图片，而 data 为原始数据。您可以通过查看UIImage的bd_isDidScaleDown属性布尔值判断图片是否发生了缩小。

设置下载器默认 Headers

为 http/https 请求增加一些自定义的 headers，支持全局设置和单独请求设置。代码示例如下所示：

[BDWebImageManager sharedManager].downloadManagerDefaultHeaders = @{@"custom-key": @"custom-val"};
   

BDWebImageRequestConfig *config = [BDWebImageRequestConfig new];
config.requestHeaders =  @{@"custom-key": @"custom-val"};
   

设置下载默认超时

适用于弱网环境，可以避免因加载等待时间过长产生不佳的用户体验，当前仅支持 Chrome 下载器和 NSURLSession 下载器。

/**
服务器响应 Chrome 下载器的默认超时时间
*/
[BDWebImageManager sharedManager].timeoutInterval = 15;
   

/**
服务器响应的 NSURLSession 下载器默认超时时间
*/
[BDWebImageManager sharedManager].timeoutInterval = 30;
   

如果资源下载超时，Chrome 下载器只要在timeoutInterval内有数据流产生就不会发生下载中断。则资源下载默认超时时间设置仅针对 NSURLSession 下载器有效，默认超时时间为 30s。代码示例如下所示：

/**
资源下载的默认超时时间，只针对 BDImageProgressiveDownload 生效
*/
[BDWebImageManager sharedManager].timeoutIntervalForResource = 30;

支持原生播放动图

BDImage在动图播放做了许多优化，需要与BDImageView一起使用。如果您需要在原生的UIImageView、UIButton上播放动图，需要接入以下方法适配系统接口。代码示例如下所示：

// 加载本地的动图
UIImageView *imageView = [UIImageView new];
BDImage *image = [BDImage imageWithContentsOfFile:path];
[image preloadAllFrames];
imageView.image = image;
      
// 加载网络的动图
// imageview/button bd_setImageWithURL方法与原来接口不变, 不需要额外设置
[imageView bd_setImageWithURL:[NSURL URLWithString:url]];
      
// BDWebImageManager requestImage 等方法，需要指定生成支持原生播放的动图
[[BDWebImageManager sharedManager] requestImage:[NSURL URLWithString:url] options:BDImageRequestPreloadAllFrames complete:^(BDWebImageRequest *request, UIImage *image, NSData *data, NSError *error, BDWebImageResultFrom from) {
	
}];

图片降采样

• 通过UIImageView-Category / UIButton-Category方式请求图片时，支持三种方式开启降采样：1. 自行传 size 2. 开启全局降采样；3. 针对某个 imageView 开启降采样，并按照 1 > 2 = 3 优先级生效。代码示例如下所示：

// 1. 自行传 size
BDWebImageRequestConfig *config = BDWebImageRequestConfig.new;
config.sizeLimit = CGSizeMake(1920, 1080)    // 长宽 1920*1080 限制
config.memoryLimit = 1024 * 1024 * 4;        // 4 MB 内存占用限制

[imageView bd_setImageWithURL:[NSURL urlWithString:@"xxx"]
              alternativeURLs:nil
                  placeholder:nil
                      options:BDImageRequestDefaultOptions
                       config:config
                       blocks:nil];

// 2. 开启全局降采样
[BDWebImageManager sharedManager].enableAllImageDownsample = YES;

// 3. 打开降采样开关，图片请求会传入 view 的 size
[imageView setBd_isOpenDownsample:YES];

// 如果通过上面的 2&3 方法开启降采样，则必须保证 imageView 的 size 已经被初始化；否则降采样将不生效。
// 您可以传一个兜底的 downsample size（优先判断 imageView 的 size，若没有则使用传入的这个 size），方法如下：
[BDWebImageManager sharedManager].allImageDownsampleSize = CGSizeMake(width, height);

• 通过Manager方式请求图片，可通过指定 size 限制图片采样大小。Size == CGSizeZero 或 view 在发起图片请求时 size 未知，均不会进行降采样。代码示例如下所示：

// 同时请求多个不同 size 的同一张图片，会解码并缓存多个 size 的图片
[[BDWebImage shareManager] requestImage:url
                                options:options
                                   size:CGSizeMake(width, height)
                               complete:complete];

图片渲染

您可以通过关闭图片渲染功能来禁止不符合预期的超大图片渲染，禁止渲染后系统仅会返回NSData 数据而不夹带图片，与网络下载图片失败效果相同。代码示例如下所示：

BDWebImageManager.shouldDecodeImageBlock = ^(BDImageMetaInfo info) {
    info.memoryFootprint;    // 预计内存消耗
    info.height/width;       // 图片长度宽度
    info.webURL;             // 请求图片的 URL
    
    return YES;   // 返回 YES 允许渲染
    return NO;    // 返回 NO  禁止渲染
};

Live Photo 加载

veImageX 已支持对 Live Photo 图像进行加载，您可通过创建BDLivePhotoView实例，并设置图像 URL，来完成 Live Photo 的加载。由于 Live Photo 本质上是由静图与视频的组合，所以您需要分别提供静图和视频的 URL，SDK 将自动拼接完成静图的展示并播放视频。BDLivePhotoView接口说明如下所示：

/**
 * @method setLivePhotoWithImageUrl:videoUrl:placeholder:completion:
 * @param imageUrl 当前请求 LivePhoto 图片的静图 URL 链接
 * @param videoUrl 当前请求 LivePhoto 图片的视频 URL 链接
 * @param placeholder 占位图，可以传入 nil
 * @param completion 图片下载完成，或者视频下载完成，都会通过该 block 进行数据回调
 * @discussion 创建并发起 LivePhoto 图片请求
 */
- (void)setLivePhotoWithImageUrl:(nullable NSURL *)imageUrl videoUrl:(nullable NSURL *)videoUrl placeholder:(nullable UIImage *)placeholder completion:(nullable BDLivePhotoCompletedBlock)completion;

/**
 * @method resetView
 * @discussion 清空 View，即把静图清空，且把视频停止播放并释放相关资源
 */
- (void)resetView;

/**
 * @method clearMemoryCache
 * @discussion 清空所有的 LivePhoto 内存缓存
 */
+ (void)clearMemoryCache;

/**
 * @method clearDiskCache
 * @discussion 清空所有的 LivePhoto 磁盘缓存
 */
+ (void)clearDiskCache;

具体操作示例如下所示：

// 创建 BDLivePhotoView
BDLivePhotoView *livePhotoView = [BDLivePhotoView new];
// 使用 imageUrl 和 videoUrl 加载 live photo
[livePhotoView setLivePhotoWithImageUrl:imageUrl videoUrl:videoUrl placeholder:nil completion:nil];

日志上报

在 1.35.2.3 及之后 SDK 版本已支持开启大图监控日志和感知日志上报能力，您可在控制台查看相关指标。其中您需要在通过 UIImageView+BDWebImage.h 提供的方法加载图片后，才会上报大图监控数据和感知日志数据。

BDWebImageManager.sharedManager.isMonitorLargeImage = YES; //开启大图监控日志上报
BDWebImageRequest.largeImageViewResolutionScaleLimit = 2; // 判断是否为大图的图片尺寸阈值，默认为大于展示 view 尺寸的 2 倍
BDWebImageRequest.largeImageFileSizeLimit = 10 * 1024 * 1024; // 判断是否为大图的文件大小阈值，默认为20MB
BDWebImageRequest.largeImageMemoryLimit = 1440 * 810; // 判断是否为大图的内存占用阈值，默认为屏幕尺寸内存大小
   

BDWebImageManager.sharedManager.enableSensibleMonitorWithLogType = YES;//开启感知日志上报
   

埋点日志上报回调

支持通过监听回调的方式获取图片日志，可用于搭建符合业务特性的数据指标体系，进行个性化数据分析。支持功能如下所示：

void *callbackIdentifier = [BDImageMonitorListener registerMonitorCallback:^(NSString * _Nonnull logType, NSDictionary * _Nullable attributes, id  _Nullable extra0, id  _Nullable extra1) {
    // 上报逻辑
}];
   

[BDImageMonitorListener unregisterMonitorCallback:callbackIdentifier];
   

加载加密图片

支持对加密图片进行解密后转码并展示，解密所需参数如下：

• 加密图片访问地址：图片 URL。

• 公钥：您在 veImageX 控制台获取的数据加密密钥，用于解密对称密钥。

• 对称密钥：您在上传 SDK 用于加密文件的加密密钥，用于解密加密数据。

BDWebImageCryptoKey *key = [BDWebImageCryptoKey new];
key.asymmetricPublicKey = pubKey; //公钥
key.symmetricKey = urlKey;  //对称密钥
[BDImageStaticConfig sharedConfig].cryptoKey = key;
[BDImageStaticConfig sharedConfig].encryptedImageUrlsDic[url] = @"1";
[imageView bd_setImageWithURL:url];  //图片 URL

云控配置下发

在 1.35.2.3 及之后 SDK 版本已支持在控制台动态下发客户端 SDK 配置参数，实现策略最优的目的，SDK 会在特定场景下拉取云控配置参数。并根据云控配置来控制相关功能，具体请参考客户端配置下发。