SDWebImage: що це, ключові поняття та UIImageView

Що таке SDWebImage?

SDWebImage — це бібліотека для асинхронного завантаження зображень на платформах Apple (iOS, macOS, tvOS, watchOS). Вона надає категорію для UIImageView з методом sd_setImage, який однією рядком завантажує, кешує та відображає зображення з будь-якого джерела.

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

Архітектура побудована на ланцюзі компонентів: Coder (декодування), Cache (зберігання), Loader (мережа) та Transformer (обробка). Кожен компонент замінний, що дозволяє адаптувати бібліотеку під конкретні вимоги проєкту.

Як працює SDWebImage: менеджер та кеш

SDWebImageManager — центральний компонент, який координує процес завантаження. Він приймає URL, перевіряє кеш, завантажує дані, декодує їх у UIImage та передає в ImageView або Completion Handler. Менеджер працює через синглтон shared, доступний з будь-якої точки додатка.

Процес завантаження

Менеджер послідовно перевіряє Кеш в пам’яті (NSDictionary з UIImage), потім Кеш на диску (файлова система). При промаху виконується мережевий запит через NSURLSession. Після завантаження дані декодуються, проходять через трансформації та зберігаються в обох кешах. Весь процес виконується в фоновій черзі, результат доставляється в головну чергу.

• Кеш в пам’яті — перевірка за O(1), зберігання UIImage з врахуванням ліміту пам’яті
• Кеш на диску — читання з файлової системи, зберігання стислених даних
• NSURLSession — завантаження з підтримкою HTTP/2 та конфігурованим часом очікування

Категорія UIImageView

UIImageView+WebCache — категорія Objective-C (доступна з Swift), яка додає метод sd_setImage. Цей метод приймає URL, placeholder, опції (SDWebImageOptions) та блок завершення. Категорія автоматично скасовує попередній запит при повторному використанні комірки таблиці через механізм sd_cancelCurrentImageLoad.

Основні класи SDWebImage

Архітектура SDWebImage розділена на кілька модулів з чіткими зонами відповідальності. Кожен клас вирішує одне завдання — від завантаження до відображення.

SDWebImageManager

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

SDImageCache

SDImageCache — дворівневий кеш (пам’ять + диск), ініціалізований з унікальним простором імен. Кеш в пам’яті зберігає UIImage з конфігурованим лімітом (за замовчуванням — до витіснення system memory warning). Кеш на диску зберігає дані в директорії Library/Caches з налаштовуваним терміном зберігання (за замовчуванням 7 днів).

SDWebImageDownloader

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

Архітектура кешування SDWebImage

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

При отриманні попередження пам’яті iOS сповіщає SDImageCache через UIApplicationDidReceiveMemoryWarningNotification, після чого кеш в пам’яті повністю очищається. Кеш на диску очищається по 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 з унікальним простором імен, який передається в 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