You need to enable JavaScript to run this app.
导航

功能接入

最近更新时间2024.03.27 18:47:01

首次发布时间2023.02.10 14:44:01

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

渐进式图片加载

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

  • 动图:gif、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];

重试次数

说明

重试次数支持在控制台 SDK 配置下发进行设置。

如果遇到超时、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];

图片缓存

说明

图片缓存支持在控制台 SDK 配置下发进行设置。

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

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;

跳过解码过程

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

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

缓存控制

说明

缓存控制支持在控制台 SDK 配置下发进行设置。

如果您需要对图片库的缓存做额外的定制,您可以注册新的缓存管理实例,控制图片缓存大小,通过自定义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 为原始数据。您可以通过查看UIImagebd_isDidScaleDown属性布尔值判断图片是否发生了缩小。

设置下载器默认 Headers

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

设置下载器默认 Headers 的全局设置,代码示例如下所示:
[BDWebImageManager sharedManager].downloadManagerDefaultHeaders = @{@"custom-key": @"custom-val"};
   

设置下载默认超时

说明

设置下载默认超时支持在控制台 SDK 配置下发进行设置。

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

服务器响应 Chrome 下载器默认超时时间为 15s,代码示例如下所示:
/**
服务器响应 Chrome 下载器的默认超时时间
*/
[BDWebImageManager sharedManager].timeoutInterval = 15;
   

如果资源下载超时,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) {
	
}];

图片降采样

说明

图片降采样支持在控制台 SDK 配置下发进行设置。

  • 通过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];

说明

您可在客户端 APP 长按图片来播放视频。

模糊图占位

支持通过模糊图占位能力,使弱网情况下完整图未下载或未解码完成时,客户端能首先加载模糊图,以提升用户体验。当完整图加载完成并成功解码后,将替换模糊图并展示。veImageX 支持加载本地模糊图和加载网络模糊图两种方式。

  • 加载本地模糊图的优先级大于加载网络模糊图。

  • 加载本地模糊图的加载速度大于加载网络模糊图。

  • 您需要自行管理本地模糊图的数据。

参考以下代码示例,传入指定的 BlurHash 码和完整图加载 URL。

说明

参考获取图片 BlurHash 码文档,了解如何获取指定图片的 BlurHash 码(模糊图)。

BDBlurHashConfig *config = [BDBlurHashConfig new];
config.blurHash = @"L~Gl#8j[fQj[1-a}fQa}.*jbfQjb"; //指定待加载的模糊图字符串,即 blurhash 码
config.targetSize = CGSizeMake(30, 30); //模糊图加载尺寸,单位为 px,取值越大,解码越慢。请根据业务需要,适当调整。
    
BDWebImageRequestConfig *requestConfig = [[BDWebImageRequestConfig alloc] init];
requestConfig.blurHashConfig = config;
    
NSURL *imageURL = [NSURL URLWithString: @"https://test.net/tos-cn-i-serviceid/demo.jpg"]; //指定待加载的完整图 URL
[self.blurHashImageView bd_setImageWithURL:imageURL alternativeURLs:nil placeholder:nil options:BDImageRequestIgnoreCache config:reConfig blocks:nil];
   

日志上报

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

说明

性能日志上报默认开启,您无需手动修改参数。

命中大图条件如下所示:

  1. 图片文件大小超过阈值,默认值为 20 MB。
  2. 图片分辨率大小超过阈值,即大于展示 view 尺寸的倍数阈值,默认值为 2 倍。
  3. 图片内存大小超过阈值,默认值为屏幕尺寸内存大小。

说明

若某张图片命中了多个条件,则将在多个命中维度下上报该条图片数据。具体请前往感知指标监控-大图监控查看日志上报数据。

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

埋点日志上报回调

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

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

加载加密图片

说明

  • 您可参考最佳实践-全链路数据加解密 进行上传文件加解密全流程操作。
  • 如果您想在加载图片之前对其进行处理,可以使用 BDWebImage 库提供的图片处理功能。

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

  • 加密图片访问地址:图片 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 会在特定场景下拉取云控配置参数。并根据云控配置来控制相关功能,具体请参考客户端配置下发