Kingfisher — vad är det, nyckelbegrepp och ImageCache

Vad är Kingfisher?

Kingfisher — ett bibliotek för asynkron laddning och cachning av bilder på Apple-plattformar, helt skrivet i Swift. Författaren till biblioteket är Wei Wang (onevcat). Kingfisher tillhandahåller en uppsättning verktyg för att ladda bilder från nätverket med automatisk cachning, transformationer och stöd för moderna Swift-teknologier: async/await, Combine, Sendable.

Biblioteket har över 23 000 stjärnor på GitHub och används i applikationer som Telegram, Snapchat och Dropbox. Kingfisher stödjer GIF, APNG, HEIF och alla standardbildformat. Varje begäran returnerar en typ-safe Result, vilket eliminerar typkonverteringsfel.

Kingfishers arkitektur är uppbyggd på tre huvudkomponenter: Manager (laddningshanterare), Cache (tvånivåcache) och Processor (transformationer). Dessa komponenter är sammankopplade via protokoll, vilket möjliggör utbyte av vilken del som helst utan att ändra beroenden.

Hur fungerar Kingfisher: Manager och Cache

KingfisherManager — den centrala klassen som samordnar laddning, cachning och bearbetning av bilder. Den innehåller referenser till ImageCache och ImageDownloader och tillhandahåller en enhetlig metod retrieveImage som returnerar den färdiga bilden efter att ha passerat alla steg.

Laddningsprocess

När retrieveImage anropas kontrollerar Manager först Memory Cache — NSCache med UIImage, där nyckeln bildas från källans URL och CacheSerializer. Om bilden hittas — returneras den omedelbart. Vid miss kontrolleras Disk Cache — läsning från filsystemet med dekryptering via serializer. Om cachen på disken är tom utförs en nätverksbegäran via ImageDownloader, resultatet avkodas, transformeras och sparas i båda cachenivåerna.

• Memory Cache — NSCache-baserad, rensas automatiskt vid minnesvarning
• Disk Cache — filagring med TTL och kontroll av storleksgräns
• ImageDownloader — URLSession-baserad med stöd för ändring av begäran via modifierare

Swift Concurrency

Från och med version 7.0 stödjer Kingfisher fullt ut async/await. Metoden retrieveImage är tillgänglig som en asynkron funktion som returnerar Result direkt utan completion-block. Detta gör det möjligt att använda biblioteket i moderna Swift-arkitekturer med Structured Concurrency.

Kingfishers huvudmoduler

Kingfisher är uppdelat i flera moduler, som var och en löser sin egen uppgift. Denna uppdelning förenklar testning och utbyte av komponenter.

KingfisherManager

KingfisherManager — en fasad som kombinerar laddning, cache och processorer. Som standard används singleton KingfisherManager.shared, men en separat instans med anpassade inställningar kan skapas för isolerade scenarier (t.ex. för enhetstester).

ImageCache

ImageCache — tvånivåcache med separata inställningar för minne och disk. Memory Cache har ingen gräns för antalet objekt men rensas av systemet vid minnesbrist. Disk Cache lagrar filer i en katalog med TTL-inställningar (standard 7 dagar), storleksgräns (standard 0 — obegränsad) och automatisk rensning.

ImageProcessor

ImageProcessor — protokoll med en enda metod process(item:options:) som returnerar den bearbetade bilden. Inbyggda implementationer: ResizingImageProcessor (storleksändring), RoundCornerImageProcessor (rundning), BlurImageProcessor (Gaussisk oskärpa), OverlayImageProcessor (färgläggning). Processorer kan kombineras med operatorn |>.

Kingfishers cachesystem

Kingfishers cachearkitektur är baserad på principen write-through: data skrivs samtidigt på båda nivåerna och läsning börjar från den snabbaste nivån — minnet. Cachenyckeln är bildens absoluta URL efter borttagning av frågeparametrar.

För att hantera Disk Cache-storleken används beräkning av total filstorlek med sortering efter senaste åtkomstdatum. När gränsen överskrids tas filer med äldst åtkomstdatum bort tills storleken sjunker under 50 % av gränsen. TTL-rensning sker vid cacheinitiering och vid varje anrop av cleanExpired.

Exempel på att använda Kingfisher i Swift

Kingfisher tillhandahåller flera gränssnitt för att ladda bilder: tillägg på UIImageView, separat hanterare och SwiftUI View.

Ladda i UIImageView via kf

kf — namespace-egenskapen på UIImageView som tillhandahåller metoderna setImage, cancelDownload och laddningsindikatorer. Metoden setImage accepterar URLSource och valfria parametrar Options och 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("Laddad \(receivedSize) / \(totalSize)")
    }
)

Metoden returnerar DownloadTask, som stödjer annullering via cancel och spårning av förlopp. Internt anropar setImage KingfisherManager.shared.retrieveImage med automatisk bestämning av ImageView som Target.

Användning med async/await

Från Kingfisher 7.0 är metoden setImage tillgänglig i asynkron version. Detta möjliggör integration av bildladdning i Swift Structured Concurrency utan 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 innehåller UIImage
    } catch {
        print("Misslyckades: \(error)")
    }
}

KFImage för SwiftUI

KFImage — SwiftUI View, liknande AsyncImage från iOS 15, men med fullt stöd för Kingfisher-cachning. View använder automatiskt KingfisherManager.shared, men stödjer anpassad hanterare via modifieraren .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)
    }
}

Laddningsindikatorer i Kingfisher

Kingfisher tillhandahåller ett inbyggt indikatorsystem för att visa bildladdningsförlopp. IndicatorType — en uppräkning med tre varianter: .activity (UIActivityIndicatorView), .progress (UIProgressView) och .custom (anpassad implementering av protokollet Indicator). Indikatorn visas automatiskt på ImageView under laddning och döljs efter slutförande.

För en anpassad indikator måste protokollet Indicator implementeras med metoderna startAnimatingView() och stopAnimatingView(). Detta möjliggör användning av hybridlösningar: skelett med shimmer-animation, ersättningsbild med gradvis visning eller logotyp med transparensanimation. Kingfisher stödjer också global inställning av indikator via KingfisherManager.shared.defaultOptions.

Kingfisher vs SDWebImage

På iOS-plattformen är Kingfisher och SDWebImage de två dominerande biblioteken för bildladdning. Valet mellan dem beror på projektets språk, prestandakrav och ekosystem.

Kingfishers största fördel är Swift-first-arkitekturen: fullt stöd för async/await, Combine Publishers, Sendable och Result-typer. SDWebImage behåller sin ledning tack vare ett bredare plugin-ekosystem (WebP, SVG, MapKit) och stöd för Objective-C.

Konfigurera Kingfisher i ett iOS-projekt

Kingfisher installeras via Swift Package Manager, CocoaPods eller Carthage. Efter installation räcker det att importera modulen och anropa valfri laddningsmetod — biblioteket är redo att användas utan ytterligare konfiguration.

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

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

För att anpassa globala inställningar används KingfisherManager.shared. Laddarens timeout, cachstrategi och standardprocessorer kan ändras. Nedan är ett exempel på cachekonfiguration på 500 MB med TTL på 14 dagar.

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 konfigureras även via hanteraren: en anpassad URLSessionConfiguration med timeouts, rubriker och cachningspolicyer kan ställas in. För att övervaka förlopp finns modulen KFIndicator med stöd för ActivityIndicator, ProgressView och anpassade indikatorer.