Kingfisher — wat is het, kernbegrippen en ImageCache

Wat is Kingfisher?

Kingfisher — een bibliotheek voor asynchroon laden en cachen van afbeeldingen op Apple-platforms, volledig geschreven in Swift. De auteur van de bibliotheek is Wei Wang (onevcat). Kingfisher biedt een set tools voor het laden van afbeeldingen van het netwerk met automatisch cachen, transformaties en ondersteuning voor moderne Swift-technologieën: async/await, Combine, Sendable.

De bibliotheek heeft meer dan 23 000 sterren op GitHub en wordt gebruikt in apps zoals Telegram, Snapchat en Dropbox. Kingfisher ondersteunt GIF, APNG, HEIF en alle standaard afbeeldingsformaten. Elk verzoek retourneert een typeveilige Result, waardoor typeconvertiefouten worden geëlimineerd.

De architectuur van Kingfisher is gebouwd op drie hoofdcomponenten: Manager (laadmanager), Cache (tweelaagse cache) en Processor (transformaties). Deze componenten zijn verbonden via protocollen, waardoor elk onderdeel kan worden vervangen zonder de afhankelijkheden te wijzigen.

Hoe werkt Kingfisher: Manager en Cache

KingfisherManager — de centrale klasse die het laden, cachen en verwerken van afbeeldingen coördineert. Het bevat verwijzingen naar ImageCache en ImageDownloader en biedt een uniforme methode retrieveImage die het voltooide beeld retourneert na het doorlopen van alle fasen.

Laadproces

Bij het aanroepen van retrieveImage controleert Manager eerst de Memory Cache — NSCache met UIImage, waarbij de sleutel wordt gevormd uit de bron-URL en CacheSerializer. Als de afbeelding wordt gevonden — wordt deze onmiddellijk geretourneerd. Bij een misser wordt de Disk Cache gecontroleerd — uitlezen van het bestandssysteem met ontsleuteling via serializer. Als de cache op schijf leeg is, wordt een netwerkverzoek uitgevoerd via ImageDownloader, het resultaat wordt gedecodeerd, getransformeerd en opgeslagen in beide cacheniveaus.

• Memory Cache — NSCache-gebaseerd, wordt automatisch gewist bij geheugenwaarschuwing
• Disk Cache — bestandsopslag met TTL en controle van de grootte limiet
• ImageDownloader — URLSession-gebaseerd met ondersteuning voor verzoekwijziging via modificatoren

Swift Concurrency

Sinds versie 7.0 ondersteunt Kingfisher volledig async/await. De methode retrieveImage is beschikbaar als een asynchrone functie die rechtstreeks Result retourneert zonder completion-blokken. Dit maakt het mogelijk de bibliotheek te gebruiken in moderne Swift-architecturen met Structured Concurrency.

Belangrijkste modules van Kingfisher

Kingfisher is verdeeld in verschillende modules, die elk hun eigen taak oplossen. Deze verdeling vereenvoudigt het testen en vervangen van componenten.

KingfisherManager

KingfisherManager — een facade die laden, cache en verwerkers combineert. Standaard wordt de singleton KingfisherManager.shared gebruikt, maar er kan een aparte instantie worden gemaakt met aangepaste instellingen voor geïsoleerde scenario’s (bijvoorbeeld voor unittesten).

ImageCache

ImageCache — tweelaagse cache met aparte instellingen voor geheugen en schijf. Memory Cache heeft geen limiet op het aantal objecten, maar wordt door het systeem gewist bij geheugentekort. Disk Cache slaat bestanden op in een map met TTL-instellingen (standaard 7 dagen), grootte limiet (standaard 0 — onbeperkt) en automatische opschoning.

ImageProcessor

ImageProcessor — protocol met een enkele methode process(item:options:) die het verwerkte beeld retourneert. Ingebouwde implementaties: ResizingImageProcessor (formaat wijzigen), RoundCornerImageProcessor (afronden), BlurImageProcessor (Gaussiaans vervagen), OverlayImageProcessor (kleur toevoegen). Processors kunnen worden gecombineerd met de operator |>.

Cachesysteem van Kingfisher

De cache-architectuur van Kingfisher is gebaseerd op het write-through principe: gegevens worden gelijktijdig op beide niveaus geschreven en het lezen begint op het snelste niveau — het geheugen. De cachesleutel is de absolute URL van de afbeelding na het verwijderen van queryparameters.

Voor het beheren van de Disk Cache-grootte wordt de totale bestandsgrootte berekend met sortering op datum van laatste toegang. Bij overschrijding van de limiet worden bestanden met de oudste toegangsdatum verwijderd totdat de grootte onder 50% van de limiet zakt. TTL-opschoning vindt plaats bij initialisatie van de cache en bij elke aanroep van cleanExpired.

Voorbeelden van Kingfisher gebruiken in Swift

Kingfisher biedt verschillende interfaces voor het laden van afbeeldingen: extensie op UIImageView, aparte manager en SwiftUI View.

Laden in UIImageView via kf

kf — de namespace-eigenschap op UIImageView die methoden setImage, cancelDownload en laadindicatoren biedt. De methode setImage accepteert URLSource en optionele parameters Options en 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("Geladen \(receivedSize) / \(totalSize)")
    }
)

De methode retourneert DownloadTask, die annulering via cancel en voortgangscontrole ondersteunt. Intern roept setImage KingfisherManager.shared.retrieveImage aan met automatische bepaling van ImageView als Target.

Gebruik met async/await

Sinds Kingfisher 7.0 is de methode setImage beschikbaar in de asynchrone versie. Dit maakt integratie van het laden van afbeeldingen in Swift Structured Concurrency mogelijk zonder 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 bevat UIImage
    } catch {
        print("Mislukt: \(error)")
    }
}

KFImage voor SwiftUI

KFImage — SwiftUI View, vergelijkbaar met AsyncImage uit iOS 15, maar met volledige ondersteuning voor Kingfisher-caching. De View gebruikt automatisch KingfisherManager.shared, maar ondersteunt een aangepaste manager via de .configure modifier.

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

Laadindicatoren in Kingfisher

Kingfisher biedt een ingebouwd indicatorsysteem voor het weergeven van de voortgang van het laden van afbeeldingen. IndicatorType — een opsomming met drie varianten: .activity (UIActivityIndicatorView), .progress (UIProgressView) en .custom (aangepaste implementatie van het Indicator-protocol). De indicator wordt automatisch op de ImageView weergegeven tijdens het laden en verborgen na voltooiing.

Voor een aangepaste indicator moet het Indicator-protocol worden geïmplementeerd met methoden startAnimatingView() en stopAnimatingView(). Dit maakt het gebruik van hybride oplossingen mogelijk: skelet met shimmer-animatie, placeholder-afbeelding met geleidelijke weergave of logo met transparantie-animatie. Kingfisher ondersteunt ook het globaal instellen van de indicator via KingfisherManager.shared.defaultOptions.

Kingfisher vs SDWebImage

Op het iOS-platform zijn Kingfisher en SDWebImage de twee dominante bibliotheken voor het laden van afbeeldingen. De keuze tussen hen hangt af van de projecttaal, prestatie-eisen en het ecosysteem.

Het belangrijkste voordeel van Kingfisher is de Swift-first architectuur: volledige ondersteuning voor async/await, Combine Publishers, Sendable en Result-types. SDWebImage behoudt zijn leiderschap vanwege het bredere plug-in-ecosysteem (WebP, SVG, MapKit) en ondersteuning voor Objective-C.

Kingfisher instellen in een iOS-project

Kingfisher wordt geïnstalleerd via Swift Package Manager, CocoaPods of Carthage. Na installatie volstaat het om de module te importeren en een laadmethode aan te roepen — de bibliotheek is klaar voor gebruik zonder extra configuratie.

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

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

Voor het aanpassen van globale instellingen wordt KingfisherManager.shared gebruikt. De time-out van de lader, de cachestrategie en de standaardprocessors kunnen worden gewijzigd. Hieronder staat een voorbeeld van een cacheconfiguratie van 500 MB met een TTL van 14 dagen.

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 wordt ook via de manager geconfigureerd: een aangepaste URLSessionConfiguration met time-outs, headers en cachebeleid kan worden ingesteld. Voor het monitoren van de voortgang is de module KFIndicator beschikbaar met ondersteuning voor ActivityIndicator, ProgressView en aangepaste indicatoren.