Kingfisher — ce que c'est, concepts clés et ImageCache

Qu'est-ce que Kingfisher ?

Kingfisher est une bibliothèque de chargement asynchrone et de mise en cache d'images sur les plateformes Apple, écrite entièrement en Swift. L'auteur de la bibliothèque est Wei Wang (onevcat). Kingfisher fournit un ensemble d'outils pour charger des images depuis le réseau avec mise en cache automatique, transformations et prise en charge des technologies Swift modernes : async/await, Combine, Sendable.

La bibliothèque a plus de 23 000 étoiles sur GitHub et est utilisée dans des applications comme Telegram, Snapchat et Dropbox. Kingfisher prend en charge GIF, APNG, HEIF et tous les formats d'image standard. Chaque requête retourne un Result type-safe, éliminant les erreurs de conversion de types.

L'architecture de Kingfisher est construite sur trois composants principaux : Manager (gestionnaire de téléchargements), Cache (cache à deux niveaux) et Processor (transformations). Ces composants sont connectés via des protocoles, permettant de remplacer n'importe quelle partie sans modifier les dépendances.

Comment fonctionne Kingfisher : Manager et Cache

KingfisherManager est la classe centrale qui coordonne le chargement, la mise en cache et le traitement des images. Elle contient des références à ImageCache et ImageDownloader et fournit une méthode unique retrieveImage qui retourne l'image prête après avoir traversé toutes les étapes.

Processus de chargement

Lors de l'appel de retrieveImage, le Manager vérifie d'abord le Memory Cache — un NSCache avec UIImage, où la clé est formée à partir de l'URL source et du CacheSerializer. Si l'image est trouvée, elle est retournée immédiatement. En cas d'échec, le Disk Cache est vérifié — lecture du système de fichiers avec déchiffrement via le sérialiseur. Si le cache disque est vide, une requête réseau est effectuée via ImageDownloader, le résultat est décodé, transformé et enregistré dans les deux niveaux de cache.

• Memory Cache — basé sur NSCache, automatiquement vidé en cas d'avertissement mémoire
• Disk Cache — stockage de fichiers avec TTL et vérification de limite de taille
• ImageDownloader — basé sur URLSession avec prise en charge de la modification de requête via des modificateurs

Swift Concurrency

À partir de la version 7.0, Kingfisher prend entièrement en charge async/await. La méthode retrieveImage est disponible en tant que fonction asynchrone, retournant Result directement sans blocs de completion. Cela permet d'utiliser la bibliothèque dans les architectures Swift modernes avec Structured Concurrency.

Modules principaux de Kingfisher

Kingfisher est divisée en plusieurs modules, chacun résolvant sa propre tâche. Cette séparation simplifie les tests et le remplacement des composants.

KingfisherManager

KingfisherManager est une façade qui combine le chargement, le cache et les processeurs. Par défaut, le singleton KingfisherManager.shared est utilisé, mais une instance séparée avec des paramètres personnalisés peut être créée pour des scénarios isolés (par exemple, pour les tests unitaires).

ImageCache

ImageCache est un cache à deux niveaux avec des paramètres séparés pour la mémoire et le disque. Le Memory Cache n'a pas de limite sur le nombre d'objets, mais le système le vide lorsque la mémoire est insuffisante. Le Disk Cache stocke les fichiers dans un répertoire avec TTL configurable (par défaut 7 jours), limite de taille (par défaut 0 — pas de limite) et nettoyage automatique.

ImageProcessor

ImageProcessor est un protocole avec une seule méthode process(item:options:) qui retourne l'image traitée. Implémentations intégrées : ResizingImageProcessor (redimensionnement), RoundCornerImageProcessor (arrondi), BlurImageProcessor (flou gaussien), OverlayImageProcessor (superposition de couleur). Les processeurs peuvent être combinés à l'aide de l'opérateur |>.

Système de cache de Kingfisher

L'architecture du cache de Kingfisher est basée sur le principe write-through : les données sont écrites simultanément sur les deux niveaux et la lecture commence par le niveau le plus rapide — la mémoire. La clé du cache est l'URL absolue de l'image après suppression des paramètres de requête.

Pour gérer la taille du Disk Cache, la taille totale des fichiers est calculée en les triant par date du dernier accès. Lorsque la limite est dépassée, les fichiers avec la date d'accès la plus ancienne sont supprimés jusqu'à ce que la taille tombe en dessous de 50 % de la limite. Le nettoyage TTL a lieu lors de l'initialisation du cache et à chaque appel de cleanExpired.

Exemples d'utilisation de Kingfisher en Swift

Kingfisher fournit plusieurs interfaces pour charger des images : une extension sur UIImageView, un gestionnaire séparé et une View SwiftUI.

Chargement dans UIImageView via kf

kf est une propriété namespace sur UIImageView qui fournit les méthodes setImage, cancelDownload et les indicateurs de chargement. La méthode setImage accepte URLSource et les paramètres optionnels Options et completionHandler.

import Kingfisher

imageView.kf.setImage(
    with: URL(string: "https://example.com/image.jpg"),
    placeholder: UIImage(named: "placeholder"),
    options: [
        .processor(RoundCornerImageProcessor(radius: .point(12))),
        .transition(.fade(0.3)),
        .cacheMemoryOnly
    ],
    progressBlock: { receivedSize, totalSize in
        print("Chargé \(receivedSize) / \(totalSize)")
    }
)

La méthode retourne un DownloadTask qui prend en charge l'annulation via cancel et le suivi de progression. En interne, setImage appelle KingfisherManager.shared.retrieveImage avec la détection automatique de ImageView comme Target.

Utilisation avec async/await

À partir de Kingfisher 7.0, la méthode setImage est disponible dans une version asynchrone. Cela permet d'intégrer le chargement d'images dans Swift Structured Concurrency sans callbacks.

func loadAvatar() async {
    do {
        let result = try await imageView.kf.setImage(
            with: url,
            options: [.processor(ResizingImageProcessor(
                targetSize: CGSize(width: 100, height: 100)
            ))]
        )
        // result.image contient UIImage
    } catch {
        print("Échec : \(error)")
    }
}

KFImage pour SwiftUI

KFImage est une View SwiftUI, similaire à AsyncImage d'iOS 15, mais avec le support complet du cache Kingfisher. La View utilise automatiquement KingfisherManager.shared mais prend en charge un gestionnaire personnalisé via le modificateur .configure.

struct AvatarView: View {
    let url: URL

    var body: some View {
        KFImage(url)
            .placeholder { ProgressView() }
            .resizable()
            .fade(duration: 0.25)
            .forceTransition()
            .frame(width: 80, height: 80)
            .cornerRadius(40)
    }
}

Indicateurs de chargement dans Kingfisher

Kingfisher fournit un système d'indicateurs intégré pour afficher la progression du chargement des images. IndicatorType est une énumération avec trois options : .activity (UIActivityIndicatorView), .progress (UIProgressView) et .custom (implémentation personnalisée du protocole Indicator). L'indicateur apparaît automatiquement au-dessus de l'ImageView pendant le chargement et se cache après la fin.

Pour un indicateur personnalisé, il est nécessaire d'implémenter le protocole Indicator avec les méthodes startAnimatingView() et stopAnimatingView(). Cela permet des solutions hybrides : un squelette avec animation shimmer, une image placeholder avec révélation progressive ou un logo avec animation d'opacité. Kingfisher prend également en charge la définition globale de l'indicateur via KingfisherManager.shared.defaultOptions.

Kingfisher vs SDWebImage

Sur la plateforme iOS, Kingfisher et SDWebImage sont les deux bibliothèques dominantes pour le chargement d'images. Le choix entre elles dépend du langage du projet, des exigences de performance et de l'écosystème.

L'avantage clé de Kingfisher est son architecture Swift-first : prise en charge complète d'async/await, Combine Publishers, Sendable et des types Result. SDWebImage maintient son leadership grâce à son écosystème de plugins plus large (WebP, SVG, MapKit) et au support d'Objective-C.

Configuration de Kingfisher dans un projet iOS

Kingfisher s'installe via Swift Package Manager, CocoaPods ou Carthage. Après l'installation, il suffit d'importer le module et d'appeler n'importe quelle méthode de chargement — la bibliothèque est prête à l'emploi sans configuration supplémentaire.

// Swift Package Manager (Package.swift)
dependencies: [
    .package(
        url: "https://github.com/onevcat/Kingfisher.git",
        from: "7.12.0"
    )
]

// CocoaPods (Podfile)
pod 'Kingfisher', '~> 7.12'

Pour personnaliser les paramètres globaux, on utilise KingfisherManager.shared. On peut modifier le temps d'attente du téléchargeur, la stratégie de cache et les processeurs par défaut. Voici un exemple de configuration d'un cache de 500 Mo avec un TTL de 14 jours.

let cache = ImageCache(name: "custom")
cache.memoryStorage.config.totalCostLimit = 100 * 1024 * 1024
cache.diskStorage.config.sizeLimit = 500 * 1024 * 1024
cache.diskStorage.config.expiration = .days(14)
KingfisherManager.shared.cache = cache

ImageDownloader est également configuré via le gestionnaire : on peut définir une URLSessionConfiguration personnalisée avec des timeouts, des en-têtes et des politiques de cache. Pour le suivi de la progression, le module KFIndicator est disponible avec le support d'ActivityIndicator, ProgressView et des indicateurs personnalisés.