SDWebImage: cos’è, concetti chiave e UIImageView

Cos’è SDWebImage?

SDWebImage è una libreria per il caricamento asincrono di immagini sulle piattaforme Apple (iOS, macOS, tvOS, watchOS). Fornisce una categoria per UIImageView con il metodo sd_setImage, che carica, memorizza nella cache e visualizza un’immagine da qualsiasi fonte in una singola riga di codice.

La libreria supporta il caricamento progressivo (l’immagine appare man mano che i byte vengono ricevuti), immagini animate (GIF, APNG), trasformazioni (arrotondamento, ritaglio, filigrana) e decoder personalizzati. Secondo GitHub Stats, SDWebImage ha oltre 25.000 stelle ed è utilizzato in applicazioni importanti, tra cui Twitter, Pinterest e Instagram.

L’architettura è costruita su una catena di componenti: Coder (decodifica), Cache (archiviazione), Loader (rete) e Transformer (elaborazione). Ogni componente è sostituibile, consentendo di adattare la libreria ai requisiti specifici del progetto.

Come funziona SDWebImage: gestore e cache

SDWebImageManager è il componente centrale che coordina il processo di caricamento. Accetta un URL, controlla la cache, carica i dati, li decodifica in UIImage e li passa a ImageView o Completion Handler. Il gestore opera tramite un singleton condiviso, accessibile da qualsiasi punto dell’applicazione.

Processo di caricamento

Il gestore controlla sequenzialmente la Memory Cache (NSDictionary con UIImage), poi la Disk Cache (file system). In caso di mancanza, viene effettuata una richiesta di rete tramite NSURLSession. Dopo il caricamento, i dati vengono decodificati, subiscono trasformazioni e vengono salvati in entrambe le cache. L’intero processo viene eseguito in una coda in background, con risultati consegnati nella coda principale.

• Memory Cache — ricerca O(1), memorizza UIImage con limite di memoria configurabile
• Disk Cache — lettura dal file system, memorizza dati compressi
• NSURLSession — caricamento con supporto HTTP/2 e timeout configurabile

Categoria UIImageView

UIImageView+WebCache è una categoria Objective-C (accessibile da Swift) che aggiunge il metodo sd_setImage. Questo metodo accetta un URL, un placeholder, opzioni (SDWebImageOptions) e un blocco di completamento. La categoria annulla automaticamente la richiesta precedente quando una cella di tabella viene riutilizzata tramite il meccanismo sd_cancelCurrentImageLoad.

Classi principali di SDWebImage

L’architettura di SDWebImage è suddivisa in diversi moduli con aree di responsabilità chiare. Ogni classe risolve un compito, dal caricamento alla visualizzazione.

SDWebImageManager

SDWebImageManager è la facciata per tutte le operazioni sulle immagini. Contiene riferimenti a ImageCache (SDImageCache) e ImageLoader (SDWebImageDownloader). Tramite il delegato SDWebImageManagerDelegate, è possibile intercettare il caricamento e modificare l’URL o il comportamento.

SDImageCache

SDImageCache è una cache a due livelli (memoria + disco) inizializzata con un namespace univoco. La Memory Cache memorizza UIImage con un limite configurabile (per impostazione predefinita — fino all’avviso di memoria di sistema). La Disk Cache memorizza i dati nella directory Library/Caches con una durata di conservazione configurabile (default 7 giorni).

SDWebImageDownloader

SDWebImageDownloader è un client HTTP basato su NSURLSession con supporto per intestazioni, timeout e tentativi. Il downloader deduplica le richieste identiche in un’unica chiamata di rete e distribuisce il risultato tra tutti gli abbonati.

Architettura della cache di SDWebImage

SDWebImage implementa una cache a due livelli con un ordine di controllo deterministico: prima la memoria, poi il disco. La chiave della cache è l’URL assoluto dell’immagine senza parametri di query o il suo hash MD5.

Quando riceve un avviso di memoria, iOS notifica SDImageCache tramite UIApplicationDidReceiveMemoryWarningNotification, dopodiché la Memory Cache viene completamente cancellata. La Disk Cache viene cancellata per TTL o quando viene superato il limite, ordinando i file per data dell’ultimo accesso.

Per la gestione manuale della cache, sono disponibili i seguenti metodi: clearMemory, clearDisk, calculateSize. La cache può essere disabilitata per richieste specifiche utilizzando le opzioni SDWebImageCacheMemoryOnly o SDWebImageAvoidAutoSetImage.

Esempi di utilizzo di SDWebImage in Swift

SDWebImage fornisce diverse interfacce per caricare le immagini: dalla semplice categoria UIImageView al gestore avanzato con elaborazione personalizzata.

Caricamento base in UIImageView

sd_setImage è il metodo principale per caricare un’immagine in UIImageView. Accetta un URL, un placeholder e parametri opzionali tramite Options e Context. Tutti i Completion Handler vengono eseguiti sul thread principale.

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

Il metodo restituisce un SDWebImageToken (operazione) che può essere annullato se necessario. Internamente, sd_setImage chiama SDWebImageManager.load, passando ImageView come Target per l’impostazione automatica dell’immagine.

Caricamento con trasformazione personalizzata

SDWebImage supporta Transformer — un protocollo con un singolo metodo transformedImage. Le trasformazioni integrate includono: cerchio, angoli arrotondati, sovrapposizione di filtri colore e ridimensionamento. Le trasformazioni possono essere combinate utilizzando l’operatore &&.

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

Utilizzo con SwiftUI

La libreria fornisce WebImage — un componente View per SwiftUI con supporto per placeholder, indicatore di progresso e gestione degli errori. Il componente si iscrive automaticamente al ciclo di vita della View e annulla il caricamento quando scompare.

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()
            }
        }
    }
}

Trasformazioni delle immagini in SDWebImage

SDWebImage fornisce un sistema flessibile di trasformazioni attraverso il protocollo SDImageTransformer. Le trasformazioni vengono applicate dopo la decodifica ma prima della cache — il risultato della trasformazione viene memorizzato su disco sotto una nuova chiave, evitando la riapplicazione in richieste successive.

Le trasformazioni integrate includono: SDImageResizingTransformer (ridimensionamento con mode), SDImageRoundCornerTransformer (angoli arrotondati con bordo opzionale), SDImageFlipTransformer (riflessione) e SDImageFilterTransformer (filtri CoreImage). La combinazione viene effettuata tramite l’operatore &&, creando una catena di elaborazione.

Per trasformazioni personalizzate, è sufficiente implementare il protocollo SDImageTransformer con il metodo transformedImageWithImage:forKey:. La chiave di trasformazione viene automaticamente aggiunta alla chiave della cache, prevenendo collisioni tra diverse versioni della stessa immagine.

Confronto SDWebImage vs Kingfisher

Sulla piattaforma iOS, i principali concorrenti di SDWebImage sono Kingfisher (Swift puro) e Nuke. La scelta tra SDWebImage e Kingfisher è spesso determinata dal linguaggio del progetto e dalla funzionalità richiesta.

SDWebImage rimane la scelta preferita per progetti in Objective-C o progetti ibridi. Kingfisher è più adatto per progetti in puro Swift grazie alla sicurezza dei tipi e alla sintassi nativa Swift. Entrambe le librerie hanno un’architettura della cache e prestazioni simili.

Configurazione di SDWebImage in un progetto iOS

SDWebImage può essere integrato tramite Swift Package Manager, CocoaPods o Carthage. La libreria è suddivisa in moduli: core (SDWebImage), Coder (formati aggiuntivi) e MapKit (per 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'
// Plugin per WebP e SVG:
pod 'SDWebImageWebPCoder'
pod 'SDWebImageSVGCoder'

Dopo l’installazione, la libreria è pronta all’uso senza configurazione aggiuntiva. Per la personalizzazione della cache, creare un’istanza di SDImageCache con un namespace univoco e passarla a SDWebImageManager durante l’inizializzazione. La configurazione globale viene effettuata tramite SDWebImageManager.shared.

// Personalizzazione della cache
let config = SDImageCacheConfig()
config.maxDiskAge = 14 * 86400 // 14 giorni invece di 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