Kingfisher — co to je, klíčové pojmy a ImageCache

Co je Kingfisher?

Kingfisher — knihovna pro asynchronní načítání a ukládání obrázků do mezipaměti na platformách Apple, napsaná kompletně ve Swiftu. Autorem knihovny je Wei Wang (onevcat). Kingfisher poskytuje sadu nástrojů pro načítání obrázků ze sítě s automatickým ukládáním do mezipaměti, transformacemi a podporou moderních Swift technologií: async/await, Combine, Sendable.

Knihovna má více než 23 000 hvězdiček na GitHubu a používá se v aplikacích jako Telegram, Snapchat a Dropbox. Kingfisher podporuje GIF, APNG, HEIF a všechny standardní formáty obrázků. Každý požadavek vrací typově bezpečný Result, který eliminuje chyby při převodu typů.

Architektura Kingfisher je postavena na třech hlavních komponentách: Manager (správce načítání), Cache (dvouúrovňová mezipaměť) a Processor (transformace). Tyto komponenty jsou propojeny přes protokoly, což umožňuje výměnu libovolné části bez změny závislostí.

Jak funguje Kingfisher: Manager a Cache

KingfisherManager — centrální třída koordinující načítání, ukládání do mezipaměti a zpracování obrázků. Obsahuje reference na ImageCache a ImageDownloader a poskytuje jednotnou metodu retrieveImage, která vrací hotový obrázek po průchodu všemi fázemi.

Proces načítání

Při volání retrieveImage Manager nejprve zkontroluje Memory Cache — NSCache s UIImage, kde klíč je tvořen z URL zdroje a CacheSerializeru. Pokud je obrázek nalezen — je okamžitě vrácen. Při neúspěchu se kontroluje Disk Cache — čtení ze souborového systému s dešifrováním přes serializer. Pokud je mezipaměť na disku prázdná, provede se síťový požadavek přes ImageDownloader, výsledek je dekódován, transformován a uložen do obou úrovní mezipaměti.

• Memory Cache — založeno na NSCache, automaticky se čistí při varování o paměti
• Disk Cache — ukládání souborů s TTL a kontrolou limitu velikosti
• ImageDownloader — založeno na URLSession s podporou úpravy požadavku přes modifikátory

Swift Concurrency

Od verze 7.0 Kingfisher plně podporuje async/await. Metoda retrieveImage je dostupná jako asynchronní funkce vracející Result přímo bez dokončovacích bloků. To umožňuje použití knihovny v moderních Swift architekturách s Structured Concurrency.

Hlavní moduly Kingfisher

Kingfisher je rozdělen do několika modulů, z nichž každý řeší svůj vlastní úkol. Toto rozdělení zjednodušuje testování a výměnu komponent.

KingfisherManager

KingfisherManager — fasáda spojující načítání, mezipaměť a procesory. Ve výchozím nastavení se používá singleton KingfisherManager.shared, ale lze vytvořit samostatnou instanci s vlastním nastavením pro izolované scénáře (např. pro unit testy).

ImageCache

ImageCache — dvouúrovňová mezipaměť s odděleným nastavením pro paměť a disk. Memory Cache nemá omezení počtu objektů, ale je systémem čištěna při nedostatku paměti. Disk Cache ukládá soubory do adresáře s nastavením TTL (výchozí 7 dní), limitem velikosti (výchozí 0 — bez omezení) a automatickým čištěním.

ImageProcessor

ImageProcessor — protokol s jedinou metodou process(item:options:) vracející zpracovaný obrázek. Vestavěné implementace: ResizingImageProcessor (změna velikosti), RoundCornerImageProcessor (zaoblení), BlurImageProcessor (Gaussovo rozmazání), OverlayImageProcessor (přidání barvy). Procesory lze kombinovat pomocí operátoru |>.

Systém mezipaměti Kingfisher

Architektura mezipaměti Kingfisher je založena na principu write-through: data se zapisují současně na obě úrovně a čtení začíná od nejrychlejší úrovně — paměti. Klíčem mezipaměti je absolutní URL obrázku po odstranění parametrů dotazu.

Pro správu velikosti Disk Cache se používá výpočet celkové velikosti souborů s řazením podle data posledního přístupu. Při překročení limitu se soubory s nejstarším datem přístupu mažou, dokud velikost neklesne pod 50 % limitu. Čištění TTL probíhá při inicializaci mezipaměti a při každém volání cleanExpired.

Příklady použití Kingfisher ve Swiftu

Kingfisher poskytuje několik rozhraní pro načítání obrázků: rozšíření na UIImageView, samostatného správce a SwiftUI View.

Načítání do UIImageView přes kf

kf — vlastnost namespace na UIImageView poskytující metody setImage, cancelDownload a indikátory načítání. Metoda setImage přijímá URLSource a volitelné parametry Options a 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("Načteno \(receivedSize) / \(totalSize)")
    }
)

Metoda vrací DownloadTask, který podporuje zrušení přes cancel a sledování průběhu. Uvnitř setImage volá KingfisherManager.shared.retrieveImage s automatickým určením ImageView jako Target.

Použití s async/await

Od Kingfisher 7.0 je metoda setImage dostupná v asynchronní verzi. To umožňuje integraci načítání obrázků do Swift Structured Concurrency bez callbacků.

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

KFImage pro SwiftUI

KFImage — SwiftUI View, podobné AsyncImage z iOS 15, ale s plnou podporou ukládání do mezipaměti Kingfisher. View automaticky používá KingfisherManager.shared, ale podporuje vlastního správce přes modifikátor .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)
    }
}

Indikátory načítání v Kingfisher

Kingfisher poskytuje vestavěný systém indikátorů pro zobrazení průběhu načítání obrázku. IndicatorType — výčet se třemi variantami: .activity (UIActivityIndicatorView), .progress (UIProgressView) a .custom (vlastní implementace protokolu Indicator). Indikátor se automaticky zobrazí na ImageView během načítání a po dokončení se skryje.

Pro vlastní indikátor je třeba implementovat protokol Indicator s metodami startAnimatingView() a stopAnimatingView(). To umožňuje použití hybridních řešení: kostra s animací shimmer, náhradní obrázek s postupným zobrazením nebo logo s animací průhlednosti. Kingfisher také podporuje globální nastavení indikátoru přes KingfisherManager.shared.defaultOptions.

Kingfisher vs SDWebImage

Na platformě iOS jsou Kingfisher a SDWebImage dvě dominantní knihovny pro načítání obrázků. Výběr mezi nimi závisí na jazyce projektu, požadavcích na výkon a ekosystému.

Klíčovou výhodou Kingfisher je Swift-first architektura: plná podpora async/await, Combine Publishers, Sendable a Result typů. SDWebImage si udržuje vedení díky širšímu ekosystému pluginů (WebP, SVG, MapKit) a podpoře Objective-C.

Nastavení Kingfisher v projektu iOS

Kingfisher se instaluje přes Swift Package Manager, CocoaPods nebo Carthage. Po instalaci stačí importovat modul a zavolat libovolnou metodu načítání — knihovna je připravena k použití bez další konfigurace.

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

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

Pro přizpůsobení globálního nastavení se používá KingfisherManager.shared. Lze změnit timeout načítače, strategii mezipaměti a výchozí procesory. Níže je příklad konfigurace mezipaměti 500 MB s TTL 14 dní.

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 také konfiguruje přes správce: lze nastavit vlastní URLSessionConfiguration s timeouts, hlavičkami a politikami ukládání do mezipaměti. Pro sledování průběhu je k dispozici modul KFIndicator s podporou ActivityIndicator, ProgressView a vlastních indikátorů.