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 singleton, достъпен от всяка точка на приложението.

Процес на зареждане

Мениджърът последователно проверява Memory Cache (NSDictionary с UIImage), след това Disk Cache (файлова система). При липса на данни се изпълнява мрежова заявка чрез NSURLSession. След зареждане данните се декодират, преминават през трансформации и се запазват и в двата кеша. Целият процес се изпълнява във фонова опашка, резултатът се доставя в main queue.

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

Категория 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 с поддръжка на хедъри, timeout и повторни опити. Изтеглячът обединява идентични заявки в едно мрежово повикване (дедупликация) и разпределя резултата между всички абонати.

Архитектура на кеширане на 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 (промяна на размер с режим), 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