SDWebImage : qu’est-ce que c’est, concepts clés et UIImageView

Qu’est-ce que SDWebImage ?

SDWebImage est une bibliothèque de chargement asynchrone d’images sur les plateformes Apple (iOS, macOS, tvOS, watchOS). Elle fournit une catégorie pour UIImageView avec la méthode sd_setImage, qui charge, met en cache et affiche une image depuis n’importe quelle source en une seule ligne de code.

La bibliothèque prend en charge le chargement progressif (l’image apparaît au fur et à mesure de la réception des octets), les images animées (GIF, APNG), les transformations (arrondi, recadrage, filigrane) et les décodeurs personnalisés. Selon GitHub Stats, SDWebImage a plus de 25 000 étoiles et est utilisé dans des applications majeures, notamment Twitter, Pinterest et Instagram.

L’architecture repose sur une chaîne de composants : Coder (décodage), Cache (stockage), Loader (réseau) et Transformer (traitement). Chaque composant est remplaçable, ce qui permet d’adapter la bibliothèque aux exigences spécifiques du projet.

Comment fonctionne SDWebImage : gestionnaire et cache

SDWebImageManager est le composant central qui coordonne le processus de chargement. Il accepte une URL, vérifie le cache, charge les données, les décode en UIImage et les transmet à ImageView ou au Completion Handler. Le gestionnaire fonctionne via un singleton partagé, accessible depuis n’importe quel point de l’application.

Processus de chargement

Le gestionnaire vérifie séquentiellement le Memory Cache (NSDictionary avec UIImage), puis le Disk Cache (système de fichiers). En cas d’échec, une requête réseau est effectuée via NSURLSession. Après le chargement, les données sont décodées, passent par des transformations et sont sauvegardées dans les deux caches. L’ensemble du processus s’exécute dans une file d’attente en arrière-plan, les résultats étant livrés dans la file principale.

• Memory Cache — recherche O(1), stocke UIImage avec une limite mémoire configurable
• Disk Cache — lecture depuis le système de fichiers, stocke des données compressées
• NSURLSession — chargement avec prise en charge HTTP/2 et délai d’attente configurable

Catégorie UIImageView

UIImageView+WebCache est une catégorie Objective-C (accessible depuis Swift) qui ajoute la méthode sd_setImage. Cette méthode accepte une URL, un placeholder, des options (SDWebImageOptions) et un bloc d’achèvement. La catégorie annule automatiquement la requête précédente lors de la réutilisation d’une cellule de tableau via le mécanisme sd_cancelCurrentImageLoad.

Classes principales de SDWebImage

L’architecture de SDWebImage est divisée en plusieurs modules avec des zones de responsabilité claires. Chaque classe résout une tâche, du chargement à l’affichage.

SDWebImageManager

SDWebImageManager est la façade de toutes les opérations sur les images. Il contient des références vers ImageCache (SDImageCache) et ImageLoader (SDWebImageDownloader). Via le délégué SDWebImageManagerDelegate, il est possible d’intercepter le chargement et de modifier l’URL ou le comportement.

SDImageCache

SDImageCache est un cache à deux niveaux (mémoire + disque) initialisé avec un espace de noms unique. Le Memory Cache stocke UIImage avec une limite configurable (par défaut — jusqu’à l’avertissement mémoire système). Le Disk Cache stocke les données dans le répertoire Library/Caches avec une durée de conservation configurable (7 jours par défaut).

SDWebImageDownloader

SDWebImageDownloader est un client HTTP basé sur NSURLSession avec prise en charge des en-têtes, des délais d’attente et des tentatives. Le téléchargeur déduplique les requêtes identiques en un seul appel réseau et distribue le résultat entre tous les abonnés.

Architecture de cache de SDWebImage

SDWebImage implémente une mise en cache à deux niveaux avec un ordre de vérification déterministe : d’abord la mémoire, puis le disque. La clé de cache est l’URL absolue de l’image sans paramètres de requête ou son hachage MD5.

Lorsqu’il reçoit un avertissement mémoire, iOS notifie SDImageCache via UIApplicationDidReceiveMemoryWarningNotification, après quoi le Memory Cache est complètement vidé. Le Disk Cache est vidé par TTL ou lorsque la limite est dépassée, en triant les fichiers par date de dernier accès.

Pour la gestion manuelle du cache, les méthodes suivantes sont disponibles : clearMemory, clearDisk, calculateSize. La mise en cache peut être désactivée pour des requêtes spécifiques via les options SDWebImageCacheMemoryOnly ou SDWebImageAvoidAutoSetImage.

Exemples d’utilisation de SDWebImage en Swift

SDWebImage fournit plusieurs interfaces pour charger des images : de la simple catégorie UIImageView au gestionnaire avancé avec traitement personnalisé.

Chargement de base dans UIImageView

sd_setImage est la méthode principale pour charger une image dans UIImageView. Elle accepte une URL, un placeholder et des paramètres optionnels via Options et Context. Tous les Completion Handler s’exécutent sur le thread 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)]
)

La méthode retourne un SDWebImageToken (opération) qui peut être annulé si nécessaire. En interne, sd_setImage appelle SDWebImageManager.load, en passant ImageView comme Target pour le réglage automatique de l’image.

Chargement avec transformation personnalisée

SDWebImage prend en charge Transformer — un protocole avec une seule méthode transformedImage. Les transformations intégrées incluent : cercle, coins arrondis, superposition de filtre couleur et redimensionnement. Les transformations peuvent être combinées à l’aide de l’opérateur &&.

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

Utilisation avec SwiftUI

La bibliothèque fournit WebImage — un composant View pour SwiftUI avec prise en charge du placeholder, de l’indicateur de progression et de la gestion des erreurs. Le composant s’abonne automatiquement au cycle de vie de la View et annule le chargement lorsqu’elle disparaît.

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

Transformations d’image dans SDWebImage

SDWebImage fournit un système de transformation flexible via le protocole SDImageTransformer. Les transformations sont appliquées après le décodage mais avant la mise en cache — le résultat de la transformation est stocké sur disque sous une nouvelle clé, évitant une réapplication lors des requêtes suivantes.

Les transformations intégrées incluent : SDImageResizingTransformer (redimensionnement avec mode), SDImageRoundCornerTransformer (coins arrondis avec bordure optionnelle), SDImageFlipTransformer (miroir) et SDImageFilterTransformer (filtres CoreImage). La combinaison s’effectue via l’opérateur &&, créant une chaîne de traitement.

Pour les transformations personnalisées, il suffit d’implémenter le protocole SDImageTransformer avec la méthode transformedImageWithImage:forKey:. La clé de transformation est automatiquement ajoutée à la clé de cache, évitant les collisions entre différentes versions d’une même image.

Comparaison SDWebImage vs Kingfisher

Sur la plateforme iOS, les principaux concurrents de SDWebImage sont Kingfisher (Swift pur) et Nuke. Le choix entre SDWebImage et Kingfisher est souvent déterminé par le langage du projet et les fonctionnalités requises.

SDWebImage reste le choix préféré pour les projets en Objective-C ou les projets hybrides. Kingfisher est mieux adapté aux projets en Swift pur grâce à la sécurité des types et à la syntaxe native Swift. Les deux bibliothèques ont une architecture de cache et des performances similaires.

Configuration de SDWebImage dans un projet iOS

SDWebImage peut être intégré via Swift Package Manager, CocoaPods ou Carthage. La bibliothèque est divisée en modules : principal (SDWebImage), Coder (formats supplémentaires) et MapKit (pour 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'
// Plugins pour WebP et SVG :
pod 'SDWebImageWebPCoder'
pod 'SDWebImageSVGCoder'

Après l’installation, la bibliothèque est prête à l’emploi sans configuration supplémentaire. Pour la personnalisation du cache, créez une instance de SDImageCache avec un espace de noms unique et transmettez-la à SDWebImageManager lors de l’initialisation. La configuration globale s’effectue via SDWebImageManager.shared.

// Personnalisation du cache
let config = SDImageCacheConfig()
config.maxDiskAge = 14 * 86400 // 14 jours au lieu de 7
config.maxDiskSize = 500 * 1024 * 1024 // 500 Mo
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