SDWebImage: ce este, concepte cheie și UIImageView

Ce este SDWebImage?

SDWebImage — bibliotecă pentru încărcarea asincronă a imaginilor pe platformele Apple (iOS, macOS, tvOS, watchOS). Oferă o categorie pentru UIImageView cu metoda sd_setImage, care încarcă, stochează în cache și afișează imaginea dintr-o singură linie de cod din orice sursă.

Biblioteca suportă încărcarea progresivă (imaginea este afișată pe măsură ce primește octeți), imagini animate (GIF, APNG), transformări (rotunjire, decupare, adăugare de filigran) și decodoare personalizate. Conform GitHub Stats, SDWebImage are peste 25 de mii de stele și este utilizat în aplicații mari, inclusiv Twitter, Pinterest și Instagram.

Arhitectura se bazează pe un lanț de componente: Coder (decodare), Cache (stocare), Loader (rețea) și Transformer (procesare). Fiecare componentă este înlocuibilă, ceea ce permite adaptarea bibliotecii la cerințele specifice ale proiectului.

Cum funcționează SDWebImage: manager și cache

SDWebImageManager — componenta centrală care coordonează procesul de încărcare. Primește URL, verifică cache-ul, încarcă datele, le decodifică în UIImage și le transmite către ImageView sau Completion Handler. Managerul funcționează prin singleton-ul shared, accesibil din orice parte a aplicației.

Procesul de încărcare

Managerul verifică succesiv Memory Cache (NSDictionary cu UIImage), apoi Disk Cache (sistemul de fișiere). În caz de lipsă a datelor, se execută o cerere de rețea prin NSURLSession. După încărcare, datele sunt decodificate, trec prin transformări și sunt salvate în ambele cache-uri. Întregul proces se desfășoară într-o coadă de fundal, rezultatul fiind livrat în main queue.

• Memory Cache — verificare în O(1), stocare UIImage cu respectarea limitei de memorie
• Disk Cache — citire din sistemul de fișiere, stocare a datelor comprimate
• NSURLSession — încărcare cu suport HTTP/2 și timeout configurabil

Categoria UIImageView

UIImageView+WebCache — categorie Objective-C (accesibilă din Swift) care adaugă metoda sd_setImage. Această metodă primește URL, placeholder, opțiuni (SDWebImageOptions) și completion-block. Categoria anulează automat cererea anterioară la reutilizarea celulei de tabel prin mecanismul sd_cancelCurrentImageLoad.

Clasele principale SDWebImage

Arhitectura SDWebImage este împărțită în mai multe module cu zone de responsabilitate clare. Fiecare clasă rezolvă o singură sarcină — de la încărcare la afișare.

SDWebImageManager

SDWebImageManager — fațada pentru toate operațiile cu imagini. Conține referințe la ImageCache (SDImageCache) și ImageLoader (SDWebImageDownloader). Prin delegatul SDWebImageManagerDelegate se poate intercepta încărcarea și modifica URL-ul sau comportamentul.

SDImageCache

SDImageCache — cache pe două niveluri (memory + disk), inițializat cu un namespace unic. Memory Cache stochează UIImage cu o limită configurabilă (implicit — până la system memory warning). Disk Cache stochează datele în directorul Library/Caches cu o perioadă de stocare configurabilă (implicit 7 zile).

SDWebImageDownloader

SDWebImageDownloader — client HTTP bazat pe NSURLSession cu suport pentru antete, timeout și reîncercări. Încărcătorul combină cererile identice într-un singur apel de rețea (deduplicare) și distribuie rezultatul între toți abonații.

Arhitectura cache SDWebImage

SDWebImage implementează stocarea în cache pe două niveluri cu o ordine de verificare deterministă: mai întâi memoria, apoi discul. Cheia cache-ului este URL-ul absolut al imaginii fără parametrii query sau hash-ul MD5 al acestuia.

La primirea memory warning, iOS notifică SDImageCache prin UIApplicationDidReceiveMemoryWarningNotification, după care Memory Cache este complet golit. Disk Cache este curățat conform TTL sau la depășirea limitei, cu sortarea fișierelor după data ultimei accesări.

Pentru gestionarea manuală a cache-ului sunt disponibile metodele: clearMemory, clearDisk, calculateSize. Stocarea în cache poate fi dezactivată pentru cereri specifice prin opțiunile SDWebImageCacheMemoryOnly sau SDWebImageAvoidAutoSetImage.

Exemple de utilizare SDWebImage în Swift

SDWebImage oferă mai multe interfețe pentru încărcarea imaginilor: de la categoria simplă UIImageView la managerul avansat cu procesare personalizată.

Încărcarea de bază în UIImageView

sd_setImage — metoda principală pentru încărcarea imaginii în UIImageView. Primește URL, placeholder și parametri opționali prin Options și Context. Toate Completion Handler-urile sunt executate în thread-ul principal.

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)]
)

Metoda returnează SDWebImageToken (o operație) care poate fi anulată dacă este necesar. În interior, sd_setImage apelează SDWebImageManager.load, transmițând ImageView ca Target pentru setarea automată a imaginii.

Încărcarea cu transformare personalizată

SDWebImage suportă Transformer — un protocol cu o singură metodă transformedImage. Transformările încorporate: cerc, rotunjire, aplicare filtru de culoare, redimensionare. Combinarea transformărilor se face cu operatorul &&.

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]
)

Utilizarea cu SwiftUI

Biblioteca oferă WebImage — o componentă View pentru SwiftUI cu suport pentru placeholder, indicator de progres și gestionarea erorilor. Componenta se abonează automat la ciclul de viață al View-ului și anulează încărcarea la dispariție.

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 în SDWebImage

SDWebImage oferă un sistem flexibil de transformare a imaginilor prin protocolul SDImageTransformer. Transformările sunt aplicate după decodare, dar înainte de stocarea în cache — rezultatul transformării este salvat pe disc sub o cheie nouă, eliminând aplicarea repetată la cererile ulterioare.

Transformările încorporate includ: SDImageResizingTransformer (redimensionare cu mod), SDImageRoundCornerTransformer (rotunjire colțuri cu bordură opțională), SDImageFlipTransformer (oglindire) și SDImageFilterTransformer (filtre CoreImage). Combinarea se face cu operatorul &&, creând un lanț de procesare.

Pentru transformări personalizate este suficient să implementați protocolul SDImageTransformer cu metoda transformedImageWithImage:forKey:. Cheia de transformare este adăugată automat la cheia cache-ului, prevenind coliziunile între diferite versiuni ale aceleiași imagini.

Compararea SDWebImage cu Kingfisher

Pe platforma iOS, principalii concurenți ai SDWebImage sunt Kingfisher (Swift pur) și Nuke. Alegerea între SDWebImage și Kingfisher depinde adesea de limbajul proiectului și de funcționalitatea necesară.

SDWebImage rămâne alegerea preferată pentru proiectele Objective-C sau proiectele hibride. Kingfisher este mai potrivit pentru proiectele Swift pur datorită siguranței tipurilor și sintaxei native Swift. Ambele biblioteci au o arhitectură de cache și viteză similare.

Configurarea SDWebImage într-un proiect iOS

Conectarea SDWebImage se face prin Swift Package Manager, CocoaPods sau Carthage. Biblioteca este împărțită în module: principal (SDWebImage), Coder (formate suplimentare) și MapKit (pentru 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'
// Pluginuri pentru WebP și SVG:
pod 'SDWebImageWebPCoder'
pod 'SDWebImageSVGCoder'

După instalare, biblioteca este gata de utilizare fără configurare suplimentară. Pentru personalizarea cache-ului se creează o instanță SDImageCache cu un namespace unic, care este transmisă către SDWebImageManager la inițializare. Configurarea globală se face prin SDWebImageManager.shared.

// Personalizarea cache-ului
let config = SDImageCacheConfig()
config.maxDiskAge = 14 * 86400 // 14 zile în loc de 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