Kingfisher — was es ist, Schlüsselkonzepte und ImageCache

Was ist Kingfisher?

Kingfisher ist eine Bibliothek für asynchrones Laden und Caching von Bildern auf Apple-Plattformen, vollständig in Swift geschrieben. Der Autor der Bibliothek ist Wei Wang (onevcat). Kingfisher bietet eine Reihe von Werkzeugen zum Laden von Bildern aus dem Netzwerk mit automatischem Caching, Transformationen und Unterstützung für moderne Swift-Technologien: async/await, Combine, Sendable.

Die Bibliothek hat über 23.000 Sterne auf GitHub und wird in Anwendungen wie Telegram, Snapchat und Dropbox verwendet. Kingfisher unterstützt GIF, APNG, HEIF und alle Standardbildformate. Jede Anfrage gibt ein typsicheres Result zurück, das Typkonvertierungsfehler ausschließt.

Die Architektur von Kingfisher basiert auf drei Hauptkomponenten: Manager (Download-Manager), Cache (zweistufiger Cache) und Processor (Transformationen). Diese Komponenten sind über Protokolle verbunden, sodass jeder Teil ausgetauscht werden kann, ohne die Abhängigkeiten zu ändern.

Wie funktioniert Kingfisher: Manager und Cache

KingfisherManager ist die zentrale Klasse, die das Laden, Caching und die Verarbeitung von Bildern koordiniert. Sie enthält Referenzen auf ImageCache und ImageDownloader und bietet eine einzige Methode retrieveImage, die das fertige Bild nach Durchlaufen aller Phasen zurückgibt.

Ladeprozess

Beim Aufruf von retrieveImage überprüft der Manager zunächst den Memory Cache — einen NSCache mit UIImage, bei dem der Schlüssel aus der Quell-URL und dem CacheSerializer gebildet wird. Wird das Bild gefunden, wird es sofort zurückgegeben. Bei einem Fehlschlag wird der Disk Cache überprüft — Lesen aus dem Dateisystem mit Entschlüsselung über den Serializer. Ist der Disk Cache leer, wird eine Netzwerkanfrage über ImageDownloader gestellt, das Ergebnis dekodiert, transformiert und in beiden Cache-Ebenen gespeichert.

• Memory Cache — NSCache-basiert, wird bei Speicherwarnung automatisch geleert
• Disk Cache — Dateispeicher mit TTL und Größenlimitprüfung
• ImageDownloader — URLSession-basiert mit Unterstützung für Anfragenmodifikation durch Modifikatoren

Swift Concurrency

Ab Version 7.0 unterstützt Kingfisher vollständig async/await. Die Methode retrieveImage ist als asynchrone Funktion verfügbar, die Result direkt ohne Completion-Blöcke zurückgibt. Dies ermöglicht die Verwendung der Bibliothek in modernen Swift-Architekturen mit Structured Concurrency.

Kernmodule von Kingfisher

Kingfisher ist in mehrere Module unterteilt, von denen jedes seine eigene Aufgabe erfüllt. Diese Trennung vereinfacht das Testen und den Austausch von Komponenten.

KingfisherManager

KingfisherManager ist eine Fassade, die Laden, Cache und Prozessoren kombiniert. Standardmäßig wird der Singleton KingfisherManager.shared verwendet, aber für isolierte Szenarien (z. B. für Unit-Tests) kann eine separate Instanz mit benutzerdefinierten Einstellungen erstellt werden.

ImageCache

ImageCache ist ein zweistufiger Cache mit getrennten Einstellungen für Speicher und Festplatte. Der Memory Cache hat keine Begrenzung der Objektanzahl, wird aber vom System bei Speicherknappheit geleert. Der Disk Cache speichert Dateien in einem Verzeichnis mit konfigurierbarem TTL (Standard 7 Tage), Größenlimit (Standard 0 — kein Limit) und automatischer Bereinigung.

ImageProcessor

ImageProcessor ist ein Protokoll mit einer einzigen Methode process(item:options:), die das verarbeitete Bild zurückgibt. Integrierte Implementierungen: ResizingImageProcessor (Größenänderung), RoundCornerImageProcessor (Abrunden), BlurImageProcessor (Gaußscher Weichzeichner), OverlayImageProcessor (Farbüberlagerung). Prozessoren können mit dem Operator |> kombiniert werden.

Caching-System von Kingfisher

Die Cache-Architektur von Kingfisher basiert auf dem Write-Through-Prinzip: Daten werden gleichzeitig auf beiden Ebenen geschrieben, und das Lesen beginnt auf der schnellsten Ebene — dem Speicher. Der Cache-Schlüssel ist die absolute Bild-URL nach Entfernen der Abfrageparameter.

Zur Verwaltung der Disk-Cache-Größe wird die Gesamtdateigröße berechnet, sortiert nach dem Datum des letzten Zugriffs. Bei Überschreitung des Limits werden die Dateien mit dem ältesten Zugriffsdatum entfernt, bis die Größe unter 50% des Limits liegt. Die TTL-Bereinigung erfolgt bei der Cache-Initialisierung und bei jedem Aufruf von cleanExpired.

Beispiele für die Verwendung von Kingfisher in Swift

Kingfisher bietet mehrere Schnittstellen zum Laden von Bildern: eine Erweiterung für UIImageView, einen separaten Manager und eine SwiftUI View.

Laden in UIImageView über kf

kf ist eine Namespace-Eigenschaft auf UIImageView, die die Methoden setImage, cancelDownload und Ladeanzeigen bereitstellt. Die Methode setImage akzeptiert URLSource und optionale Parameter Options und 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)")
    }
)

Die Methode gibt einen DownloadTask zurück, der das Abbrechen über cancel und die Fortschrittsverfolgung unterstützt. Intern ruft setImage KingfisherManager.shared.retrieveImage mit automatischer Erkennung von ImageView als Target auf.

Verwendung mit async/await

Ab Kingfisher 7.0 ist die Methode setImage in einer asynchronen Version verfügbar. Dies ermöglicht die Integration des Bildladens in Swift Structured Concurrency ohne 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 enthält UIImage
    } catch {
        print("Fehlgeschlagen: \(error)")
    }
}

KFImage für SwiftUI

KFImage ist eine SwiftUI View, ähnlich wie AsyncImage aus iOS 15, aber mit vollständiger Kingfisher-Cache-Unterstützung. Die View verwendet automatisch KingfisherManager.shared, unterstützt aber einen benutzerdefinierten Manager über den Modifikator .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)
    }
}

Ladeanzeigen in Kingfisher

Kingfisher bietet ein integriertes Anzeigesystem zur Darstellung des Bildladefortschritts. IndicatorType ist eine Aufzählung mit drei Optionen: .activity (UIActivityIndicatorView), .progress (UIProgressView) und .custom (benutzerdefinierte Implementierung des Indicator-Protokolls). Die Anzeige erscheint automatisch über dem ImageView während des Ladens und wird nach Abschluss ausgeblendet.

Für eine benutzerdefinierte Anzeige muss das Indicator-Protokoll mit den Methoden startAnimatingView() und stopAnimatingView() implementiert werden. Dies ermöglicht hybride Lösungen: ein Skelett mit Shimmer-Animation, ein Platzhalterbild mit allmählicher Einblendung oder ein Logo mit Transparenzanimation. Kingfisher unterstützt auch das globale Setzen der Anzeige über KingfisherManager.shared.defaultOptions.

Kingfisher vs SDWebImage

Auf der iOS-Plattform sind Kingfisher und SDWebImage die beiden dominierenden Bildladebibliotheken. Die Wahl zwischen ihnen hängt von der Projektsprache, den Leistungsanforderungen und dem Ökosystem ab.

Der Hauptvorteil von Kingfisher ist die Swift-first-Architektur: vollständige Unterstützung für async/await, Combine Publishers, Sendable und Result-Typen. SDWebImage behält seine Führung durch das breitere Plugin-Ökosystem (WebP, SVG, MapKit) und die Objective-C-Unterstützung.

Einrichtung von Kingfisher in einem iOS-Projekt

Kingfisher wird über Swift Package Manager, CocoaPods oder Carthage installiert. Nach der Installation genügt es, das Modul zu importieren und eine beliebige Lademethode aufzurufen — die Bibliothek ist ohne zusätzliche Konfiguration einsatzbereit.

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

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

Zur Anpassung der globalen Einstellungen wird KingfisherManager.shared verwendet. Sie können das Download-Timeout, die Cache-Strategie und die Standardprozessoren ändern. Nachfolgend ein Beispiel für die Konfiguration eines 500-MB-Caches mit 14-tägigem TTL.

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 wird ebenfalls über den Manager konfiguriert: Sie können eine benutzerdefinierte URLSessionConfiguration mit Timeouts, Headern und Caching-Richtlinien festlegen. Zur Fortschrittsüberwachung steht das KFIndicator-Modul mit Unterstützung für ActivityIndicator, ProgressView und benutzerdefinierte Anzeigen zur Verfügung.