SDWebImage: что это, ключевые понятия и UIImageView

Что такое SDWebImage?

SDWebImage — библиотека для асинхронной загрузки изображений на платформах Apple (iOS, macOS, tvOS, watchOS). Она предоставляет категорию для UIImageView с методом sd_setImage, который одной строкой загружает, кэширует и отображает изображение из любого источника.

Библиотека поддерживает прогрессивную загрузку (изображение отображается по мере получения байт), анимированные изображения (GIF, APNG), трансформации (скругление, обрезка, наложение водяного знака) и кастомные декодеры. По данным GitHub Stats, SDWebImage имеет более 25 тысяч звёзд и используется в крупных приложениях, включая Twitter, Pinterest и Instagram.

Архитектура построена на цепочке компонентов: Coder (декодирование), Cache (хранение), Loader (сеть) и Transformer (обработка). Каждый компонент заменяемый, что позволяет адаптировать библиотеку под специфические требования проекта.

Как работает SDWebImage: менеджер и кэш

SDWebImageManager — центральный компонент, координирующий процесс загрузки. Он принимает URL, проверяет кэш, загружает данные, декодирует их в UIImage и передаёт в ImageView или Completion Handler. Менеджер работает через синглтон shared, доступный из любой точки приложения.

Процесс загрузки

Менеджер последовательно проверяет Memory Cache (NSDictionary с UIImage), затем Disk Cache (файловая система). При промахе выполняется сетевой запрос через NSURLSession. После загрузки данные декодируются, проходят через трансформации и сохраняются в оба кэша. Весь процесс выполняется в фоновой очереди, результат доставляется в main queue.

• Memory Cache — проверка за O(1), хранение UIImage с учётом лимита памяти
• Disk Cache — чтение из файловой системы, хранение сжатых данных
• NSURLSession — загрузка с поддержкой HTTP/2 и конфигурируемым таймаутом

Категория UIImageView

UIImageView+WebCache — категория Objective-C (доступна из Swift), добавляющая метод sd_setImage. Этот метод принимает URL, placeholder, опции (SDWebImageOptions) и completion-блок. Категория автоматически отменяет предыдущий запрос при переиспользовании ячейки таблицы через механизм sd_cancelCurrentImageLoad.

Основные классы SDWebImage

Архитектура SDWebImage разделена на несколько модулей с чёткими зонами ответственности. Каждый класс решает одну задачу — от загрузки до отображения.

SDWebImageManager

SDWebImageManager — фасад для всех операций с изображениями. Он содержит ссылки на ImageCache (SDImageCache) и ImageLoader (SDWebImageDownloader). Через делегат SDWebImageManagerDelegate можно перехватить загрузку и изменить URL или поведение.

SDImageCache

SDImageCache — двухуровневый кэш (memory + disk), инициализируемый с уникальным namespace. Memory Cache хранит UIImage с конфигурируемым лимитом (по умолчанию — до вытеснения system memory warning). Disk Cache хранит данные в директории Library/Caches с настраиваемым сроком хранения (по умолчанию 7 дней).

SDWebImageDownloader

SDWebImageDownloader — HTTP-клиент на основе NSURLSession с поддержкой заголовков, таймаутов и повторных попыток. Загрузчик объединяет одинаковые запросы в один сетевой вызов (deduplication) и распределяет результат между всеми подписчиками.

Архитектура кэширования SDWebImage

SDWebImage реализует двухуровневое кэширование с детерминированным порядком проверки: сначала память, затем диск. Ключом кэша выступает абсолютный URL изображения без query-параметров или MD5-хэш от него.

При получении memory warning iOS уведомляет SDImageCache через UIApplicationDidReceiveMemoryWarningNotification, после чего Memory Cache полностью очищается. Disk Cache очищается по TTL или при превышении лимита, с сортировкой файлов по дате последнего доступа.

Для ручного управления кэшем доступны методы: clearMemory, clearDisk, calculateSize. Кэширование можно отключить для конкретных запросов через опцию SDWebImageCacheMemoryOnly или SDWebImageAvoidAutoSetImage.

Примеры использования SDWebImage на Swift

SDWebImage предоставляет несколько интерфейсов для загрузки изображений: от простой категории UIImageView до продвинутого менеджера с кастомной обработкой.

Базовая загрузка в UIImageView

sd_setImage — основной метод для загрузки изображения в UIImageView. Он принимает URL, placeholder и опциональные параметры через Options и Context. Все Completion Handler выполняются в главном потоке.

let imageView = UIImageView()
imageView.sd_setImage(
    with: URL(string: "https://example.com/photo.jpg"),
    placeholderImage: UIImage(named: "placeholder"),
    options: [.progressiveLoad, .retryFailed],
    context: [.imageThumbnailPixelSize : CGSize(width: 300, height: 300)]
)

Метод возвращает SDWebImageToken (операцию), которую можно отменить при необходимости. Внутри sd_setImage вызывает SDWebImageManager.load, передавая ImageView как Target для автоматической установки изображения.

Загрузка с кастомной трансформацией

SDWebImage поддерживает Transformer — протокол с единственным методом transformedImage. Встроенные трансформации: круг, скругление, наложение цветного фильтра, изменение размера. Комбинирование трансформаций выполняется оператором &&.

let transformer = SDImageResizingTransformer(
    size: CGSize(width: 200, height: 200),
    scaleMode: .aspectFill
)
let roundedTransformer = SDImageRoundCornerTransformer(
    radius: 16,
    corners: .allCorners,
    borderWidth: 0
)
imageView.sd_setImage(
    with: url,
    placeholderImage: placeholder,
    context: [.imageTransformer : transformer && roundedTransformer]
)

Использование с SwiftUI

Библиотека предоставляет WebImage — View-компонент для SwiftUI с поддержкой placeholder, индикатора прогресса и обработки ошибок. Компонент автоматически подписывается на жизненный цикл View и отменяет загрузку при исчезновении.

struct CachedImageView: View {
    let url: URL

    var body: some View {
        WebImage(url: url) { phase in
            if let image = phase.image {
                image.resizable()
            } else if phase.error {
                Color.red
            } else {
                ProgressView()
            }
        }
    }
}

Image Transformations в SDWebImage

SDWebImage предоставляет гибкую систему трансформаций изображений через протокол SDImageTransformer. Трансформации применяются после декодирования, но до кэширования — результат трансформации сохраняется на диске под новым ключом, исключая повторное применение при последующих запросах.

Встроенные трансформации включают: SDImageResizingTransformer (изменение размера с mode), SDImageRoundCornerTransformer (скругление углов с опциональной границей), SDImageFlipTransformer (зеркальное отражение) и SDImageFilterTransformer (CoreImage-фильтры). Комбинирование выполняется через оператор &&, создавая цепочку обработки.

Для кастомных трансформаций достаточно реализовать протокол SDImageTransformer с методом transformedImageWithImage:forKey:. Ключ трансформации автоматически добавляется к ключу кэша, предотвращая коллизии между разными версиями одного изображения.

Сравнение SDWebImage с Kingfisher

На iOS-платформе основными конкурентами SDWebImage являются Kingfisher (чистый Swift) и Nuke. Выбор между SDWebImage и Kingfisher часто определяется языком проекта и требуемой функциональностью.

SDWebImage остаётся предпочтительным выбором для проектов на Objective-C или гибридных проектах. Kingfisher лучше подходит для проектов на чистом Swift благодаря типовой безопасности и нативному Swift-синтаксису. Обе библиотеки имеют схожую архитектуру кэширования и скорости.

Настройка SDWebImage в проекте iOS

Подключение SDWebImage выполняется через Swift Package Manager, CocoaPods или Carthage. Библиотека разбита на модули: основной (SDWebImage), Coder (дополнительные форматы) и MapKit (для MKAnnotationView).

// Swift Package Manager (Package.swift)
dependencies: [
    .package(
        url: "https://github.com/SDWebImage/SDWebImage.git",
        from: "5.19.0"
    )
]

// CocoaPods (Podfile)
pod 'SDWebImage', '~> 5.19.0'
// Плагины для WebP и SVG:
pod 'SDWebImageWebPCoder'
pod 'SDWebImageSVGCoder'

После установки библиотека готова к использованию без дополнительной конфигурации. Для кастомизации кэша создаётся экземпляр SDImageCache с уникальным namespace, который передаётся в SDWebImageManager при инициализации. Глобальная конфигурация выполняется через SDWebImageManager.shared.

// Кастомизация кэша
let config = SDImageCacheConfig()
config.maxDiskAge = 14 * 86400 // 14 дней вместо 7
config.maxDiskSize = 500 * 1024 * 1024 // 500 MB
config.shouldCacheImagesInMemory = .true

let cache = SDImageCache(
    namespace: "custom",
    diskCacheDirectory: FileManager.default.urls(
        for: .cachesDirectory,
        in: .userDomainMask
    ).first?.appendingPathComponent("custom_cache"),
    config: config
)
SDWebImageManager.sharedImageCache = cache