Kingfisher — ce este, concepte cheie și ImageCache

Ce este Kingfisher?

Kingfisher — o bibliotecă pentru încărcarea asincronă și stocarea în cache a imaginilor pe platformele Apple, scrisă integral în Swift. Autorul bibliotecii este Wei Wang (onevcat). Kingfisher oferă un set de instrumente pentru încărcarea imaginilor din rețea cu stocare automată în cache, transformări și suport pentru tehnologiile moderne Swift: async/await, Combine, Sendable.

Biblioteca are peste 23 000 de stele pe GitHub și este utilizată în aplicații precum Telegram, Snapchat și Dropbox. Kingfisher suportă GIF, APNG, HEIF și toate formatele standard de imagini. Fiecare solicitare returnează un Result sigur din punct de vedere al tipurilor, eliminând erorile de conversie a tipurilor.

Arhitectura Kingfisher este construită pe trei componente principale: Manager (manager de încărcare), Cache (cache pe două niveluri) și Processor (transformări). Aceste componente sunt conectate prin protocoale, ceea ce permite înlocuirea oricărei părți fără a modifica dependențele.

Cum funcționează Kingfisher: Manager și Cache

KingfisherManager — clasa centrală care coordonează încărcarea, stocarea în cache și procesarea imaginilor. Conține referințe la ImageCache și ImageDownloader și oferă o metodă unică retrieveImage care returnează imaginea gata după parcurgerea tuturor etapelor.

Procesul de încărcare

La apelarea retrieveImage, Manager verifică mai întâi Memory Cache — NSCache cu UIImage, unde cheia este formată din URL-ul sursei și CacheSerializer. Dacă imaginea este găsită — este returnată imediat. În caz de lipsă, se verifică Disk Cache — citire din sistemul de fișiere cu decriptare prin serializer. Dacă cache-ul pe disc este gol, se execută o solicitare de rețea prin ImageDownloader, rezultatul este decodat, transformat și salvat în ambele niveluri de cache.

• Memory Cache — bazat pe NSCache, se curăță automat la avertizarea de memorie
• Disk Cache — stocare de fișiere cu TTL și verificare a limitei de dimensiune
• ImageDownloader — bazat pe URLSession cu suport pentru modificarea solicitării prin modificatori

Swift Concurrency

Începând cu versiunea 7.0, Kingfisher suportă complet async/await. Metoda retrieveImage este disponibilă ca funcție asincronă, returnând Result direct fără blocuri de completare. Acest lucru permite utilizarea bibliotecii în arhitecturi moderne Swift cu Structured Concurrency.

Modulele principale Kingfisher

Kingfisher este împărțită în mai multe module, fiecare rezolvând propria sarcină. Această divizare simplifică testarea și înlocuirea componentelor.

KingfisherManager

KingfisherManager — o fațadă care combină încărcarea, cache-ul și procesoarele. În mod implicit, se utilizează singleton-ul KingfisherManager.shared, dar se poate crea o instanță separată cu setări personalizate pentru scenarii izolate (de exemplu, pentru teste unitare).

ImageCache

ImageCache — cache pe două niveluri cu setări separate pentru memorie și disc. Memory Cache nu are limită de număr de obiecte, dar este curățată de sistem la lipsa de memorie. Disk Cache stochează fișierele într-un director cu setări TTL (implicit 7 zile), limită de dimensiune (implicit 0 — fără limită) și curățare automată.

ImageProcessor

ImageProcessor — protocol cu o singură metodă process(item:options:) care returnează imaginea procesată. Implementări încorporate: ResizingImageProcessor (redimensionare), RoundCornerImageProcessor (rotunjire), BlurImageProcessor (estompare gaussiană), OverlayImageProcessor (aplicare culoare). Procesoarele pot fi combinate prin operatorul |>.

Sistemul de cache Kingfisher

Arhitectura cache-ului Kingfisher se bazează pe principiul write-through: datele sunt scrise simultan în ambele niveluri, iar citirea începe de la nivelul cel mai rapid — memoria. Cheia cache-ului este URL-ul absolut al imaginii după eliminarea parametrilor de interogare.

Pentru gestionarea dimensiunii Disk Cache se utilizează calcularea dimensiunii totale a fișierelor cu sortare după data ultimei accesări. La depășirea limitei, fișierele cu cea mai veche dată de acces sunt șterse până când dimensiunea scade sub 50% din limită. Curățarea TTL are loc la inițializarea cache-ului și la fiecare apel cleanExpired.

Exemple de utilizare Kingfisher în Swift

Kingfisher oferă mai multe interfețe pentru încărcarea imaginilor: extensie pe UIImageView, manager separat și SwiftUI View.

Încărcare în UIImageView prin kf

kf — proprietatea namespace pe UIImageView care oferă metodele setImage, cancelDownload și indicatoare de încărcare. Metoda setImage acceptă URLSource și parametrii opționali Options și 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("Încărcat \(receivedSize) / \(totalSize)")
    }
)

Metoda returnează DownloadTask, care suportă anularea prin cancel și urmărirea progresului. Intern, setImage apelează KingfisherManager.shared.retrieveImage cu determinarea automată a ImageView ca Target.

Utilizare cu async/await

Începând cu Kingfisher 7.0, metoda setImage este disponibilă în versiunea asincronă. Acest lucru permite integrarea încărcării imaginilor în Swift Structured Concurrency fără callback-uri.

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

KFImage pentru SwiftUI

KFImage — SwiftUI View, similară cu AsyncImage din iOS 15, dar cu suport complet pentru cache-ul Kingfisher. View utilizează automat KingfisherManager.shared, dar suportă un manager personalizat prin modificatorul .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)
    }
}

Indicatoare de încărcare în Kingfisher

Kingfisher oferă un sistem încorporat de indicatoare pentru afișarea progresului încărcării imaginii. IndicatorType — o enumerare cu trei variante: .activity (UIActivityIndicatorView), .progress (UIProgressView) și .custom (implementare personalizată a protocolului Indicator). Indicatorul este afișat automat pe ImageView în timpul încărcării și ascuns după finalizare.

Pentru un indicator personalizat, trebuie implementat protocolul Indicator cu metodele startAnimatingView() și stopAnimatingView(). Acest lucru permite utilizarea soluțiilor hibride: schelet cu animație shimmer, imagine de substituție cu apariție treptată sau logo cu animație de transparență. Kingfisher suportă și setarea globală a indicatorului prin KingfisherManager.shared.defaultOptions.

Kingfisher vs SDWebImage

Pe platforma iOS, Kingfisher și SDWebImage sunt cele două biblioteci dominante pentru încărcarea imaginilor. Alegerea între ele depinde de limbajul proiectului, cerințele de performanță și ecosistem.

Avantajul cheie al Kingfisher este arhitectura Swift-first: suport complet pentru async/await, Combine Publishers, Sendable și tipuri Result. SDWebImage își păstrează liderul datorită ecosistemului mai larg de pluginuri (WebP, SVG, MapKit) și suportului pentru Objective-C.

Configurarea Kingfisher într-un proiect iOS

Kingfisher se instalează prin Swift Package Manager, CocoaPods sau Carthage. După instalare, este suficient să importați modulul și să apelați orice metodă de încărcare — biblioteca este gata de funcționare fără configurație suplimentară.

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

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

Pentru personalizarea setărilor globale se utilizează KingfisherManager.shared. Se poate modifica timeout-ul încărcătorului, strategia de cache și procesoarele implicite. Mai jos este un exemplu de configurare a cache-ului de 500 MB cu TTL de 14 zile.

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 se configurează și prin manager: se poate seta o URLSessionConfiguration personalizată cu timeout-uri, antete și politici de cache. Pentru monitorizarea progresului, este disponibil modulul KFIndicator cu suport pentru ActivityIndicator, ProgressView și indicatoare personalizate.