SDWebImage 使用指南：高效加载网络图片的完整方案

严微海

于 2025-06-01 09:05:30 发布

阅读量225

点赞数 3

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_01104/article/details/148361288

SDWebImage 使用指南：高效加载网络图片的完整方案

SDWebImage 项目地址: https://gitcode.com/gh_mirrors/sdw/SDWebImage

概述

SDWebImage 是一个功能强大的图片加载库，专为 iOS 和 macOS 平台设计。它提供了异步图片下载、缓存管理、图片解码等核心功能，能够显著提升应用中网络图片加载的性能和用户体验。本文将详细介绍 SDWebImage 的各种使用场景和方法。

基础用法：在 UITableView 中加载图片

在列表视图中加载图片是最常见的需求之一。SDWebImage 提供了简洁的 API 来实现这一功能。

Objective-C 实现

- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath {
    static NSString *MyIdentifier = @"MyIdentifier";
    UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:MyIdentifier];
    
    if (cell == nil) {
        cell = [[UITableViewCell alloc] initWithStyle:UITableViewCellStyleDefault
                                      reuseIdentifier:MyIdentifier];
    }
    
    [cell.imageView sd_setImageWithURL:[NSURL URLWithString:@"图片URL"]
                      placeholderImage:[UIImage imageNamed:@"占位图"]];
    
    cell.textLabel.text = @"单元格文本";
    return cell;
}

Swift 实现

func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
    let cell = tableView.dequeueReusableCell(withIdentifier: "MyIdentifier", for: indexPath)
    
    cell.imageView?.sd_setImage(with: imageUrl, placeholderImage: placeholderImage)
    cell.textLabel?.text = "单元格文本"
    
    return cell
}

使用这种方法，SDWebImage 会自动处理以下事项：

异步下载图片，不阻塞主线程
内存和磁盘缓存管理
重复请求的合并处理
单元格复用时自动取消不必要的下载

进阶功能：使用回调块

当需要更精细地控制图片加载过程时，可以使用带有回调块的 API。

[cell.imageView sd_setImageWithURL:[NSURL URLWithString:@"图片URL"]
                  placeholderImage:[UIImage imageNamed:@"占位图"]
                         completed:^(UIImage *image, NSError *error, SDImageCacheType cacheType, NSURL *imageURL) {
                             if (error) {
                                 NSLog(@"图片加载失败: %@", error.localizedDescription);
                             } else {
                                 NSLog(@"图片加载成功，来源: %@", 
                                       cacheType == SDImageCacheTypeMemory ? @"内存缓存" : 
                                       cacheType == SDImageCacheTypeDisk ? @"磁盘缓存" : @"网络下载");
                             }
                         }];

注意事项：

如果图片请求在完成前被取消，成功和失败回调都不会被执行
回调块在主线程执行，可以直接更新 UI

核心组件：SDWebImageManager

SDWebImageManager 是 UIImageView 分类背后的核心类，它将异步下载器和图片缓存结合在一起。当需要在非视图环境中使用图片下载和缓存功能时，可以直接使用这个类。

SDWebImageManager *manager = [SDWebImageManager sharedManager];
[manager loadImageWithURL:imageURL
                  options:0
                 progress:^(NSInteger receivedSize, NSInteger expectedSize) {
                     CGFloat progress = (CGFloat)receivedSize / expectedSize;
                     NSLog(@"下载进度: %.2f%%", progress * 100);
                 }
                 completed:^(UIImage *image, NSError *error, SDImageCacheType cacheType, BOOL finished, NSURL *imageURL) {
                     if (image && finished) {
                         NSLog(@"图片加载完成");
                         // 处理图片
                     } else if (error) {
                         NSLog(@"图片加载失败: %@", error.localizedDescription);
                     }
                 }];

高级选项说明：

使用 SDWebImageQueryDataWhenInMemory 选项可以在从内存缓存获取图片时同时获取原始数据
其他选项包括 SDWebImageRetryFailed（自动重试失败请求）、SDWebImageHighPriority（高优先级下载）等

独立使用下载器

SDWebImageDownloader 可以独立于缓存系统使用，适合只需要下载功能而不需要缓存的场景。

SDWebImageDownloader *downloader = [SDWebImageDownloader sharedDownloader];
[downloader downloadImageWithURL:imageURL
                         options:0
                        progress:^(NSInteger receivedSize, NSInteger expectedSize) {
                            // 进度更新
                        }
                       completed:^(UIImage *image, NSData *data, NSError *error, BOOL finished) {
                            if (image && finished) {
                                // 处理下载完成的图片
                            }
                        }];

独立使用缓存系统

SDImageCache 提供了独立的内存和磁盘缓存功能，写入磁盘的操作是异步执行的，不会阻塞 UI。

缓存查询

SDImageCache *imageCache = [[SDImageCache alloc] initWithNamespace:@"自定义命名空间"];
[imageCache queryDiskCacheForKey:cacheKey done:^(UIImage *image) {
    if (image) {
        // 使用缓存图片
    } else {
        // 图片不在缓存中，需要下载
    }
}];

缓存存储

[[SDImageCache sharedImageCache] storeImage:image 
                                    forKey:cacheKey
                                completion:^{
                                    NSLog(@"图片已缓存");
                                }];

缓存策略控制：

默认情况下图片会同时存储在内存和磁盘中
使用 storeImage:forKey:toDisk:completion: 方法可以控制是否存储到磁盘

高级技巧：缓存键过滤器

当图片 URL 包含动态参数（如访问令牌）时，可以使用缓存键过滤器来规范化缓存键。

SDWebImageManager.sharedManager.cacheKeyFilter = ^(NSURL *url) {
    // 移除查询参数，只保留基本URL部分
    NSURLComponents *components = [NSURLComponents componentsWithURL:url resolvingAgainstBaseURL:NO];
    components.query = nil;
    return [components.URL absoluteString];
};

这个技巧特别适用于以下场景：