Kingfisher — mi ez, kulcsfogalmak és ImageCache

Mi az a Kingfisher?

Kingfisher — egy könyvtár aszinkron képbetöltésre és gyorsítótárazásra Apple platformokon, teljes egészében Swift-ben írva. A könyvtár szerzője Wei Wang (onevcat). A Kingfisher egy eszközkészletet biztosít képek hálózatról történő betöltéséhez automatikus gyorsítótárazással, transzformációkkal és modern Swift technológiák támogatásával: async/await, Combine, Sendable.

A könyvtár több mint 23 000 csillaggal rendelkezik a GitHub-on, és olyan alkalmazásokban használják, mint a Telegram, Snapchat és Dropbox. A Kingfisher támogatja a GIF, APNG, HEIF és az összes szabványos képformátumot. Minden kérés egy típusbiztos Result értéket ad vissza, kiküszöbölve a típuskonverziós hibákat.

A Kingfisher architektúrája három fő komponensre épül: Manager (betöltéskezelő), Cache (kétszintű gyorsítótár) és Processor (transzformációk). Ezek a komponensek protokollokon keresztül kapcsolódnak, lehetővé téve bármely rész cseréjét a függőségek módosítása nélkül.

Hogyan működik a Kingfisher: Manager és Cache

KingfisherManager — a központi osztály, amely koordinálja a képek betöltését, gyorsítótárazását és feldolgozását. Tartalmazza az ImageCache és ImageDownloader referenciáit, és egy egységes retrieveImage metódust biztosít, amely az összes szakaszon való áthaladás után visszaadja a kész képet.

Betöltési folyamat

A retrieveImage meghívásakor a Manager először a Memory Cache-t ellenőrzi — NSCache UIImage-szel, ahol a kulcs a forrás URL-jéből és CacheSerializer-ből képződik. Ha a kép megtalálható — azonnal visszaadja. Hiány esetén a Disk Cache kerül ellenőrzésre — olvasás a fájlrendszerből a serializer általi visszafejtéssel. Ha a lemez gyorsítótár üres, hálózati kérés hajtódik végre az ImageDownloader-en keresztül, az eredmény dekódolásra, transzformálásra és mindkét gyorsítótári szinten tárolásra kerül.

• Memory Cache — NSCache-alapú, memóriafigyelmeztetéskor automatikusan törlődik
• Disk Cache — fájltárolás TTL-lel és méretkorlát ellenőrzéssel
• ImageDownloader — URLSession-alapú a kérés módosításának támogatásával módosítókon keresztül

Swift Concurrency

A 7.0 verziótól kezdve a Kingfisher teljes mértékben támogatja az async/await-et. A retrieveImage metódus elérhető aszinkron függvényként, amely közvetlenül Result-ot ad vissza completion blokkok nélkül. Ez lehetővé teszi a könyvtár használatát modern Swift architektúrákban Structured Concurrency-vel.

A Kingfisher fő moduljai

A Kingfisher több modulra van osztva, amelyek mindegyike saját feladatát oldja meg. Ez a felosztás egyszerűsíti a komponensek tesztelését és cseréjét.

KingfisherManager

KingfisherManager — egy homlokzat, amely egyesíti a betöltést, a gyorsítótárat és a processzorokat. Alapértelmezés szerint a KingfisherManager.shared szingleton használatos, de külön példány hozható létre egyéni beállításokkal izolált forgatókönyvekhez (pl. egységtesztekhez).

ImageCache

ImageCache — kétszintű gyorsítótár külön beállításokkal a memória és a lemez számára. A Memory Cache-nek nincs korlátja az objektumok számában, de a rendszer törli memóriahiány esetén. A Disk Cache fájlokat tárol egy könyvtárban TTL beállításokkal (alapértelmezett 7 nap), méretkorláttal (alapértelmezett 0 — korlátlan) és automatikus tisztítással.

ImageProcessor

ImageProcessor — protokoll egyetlen process(item:options:) metódussal, amely a feldolgozott képet adja vissza. Beépített implementációk: ResizingImageProcessor (méretváltoztatás), RoundCornerImageProcessor (lekerekítés), BlurImageProcessor (Gauss-elmosás), OverlayImageProcessor (szín hozzáadása). A processzorok kombinálhatók a |> operátorral.

A Kingfisher gyorsítótárazási rendszere

A Kingfisher gyorsítótár architektúrája a write-through elven alapul: az adatok egyidejűleg mindkét szinten íródnak, az olvasás pedig a leggyorsabb szintről — a memóriából — indul. A gyorsítótár kulcsa a kép abszolút URL-je a lekérdezési paraméterek eltávolítása után.

A Disk Cache méretének kezeléséhez a fájlok teljes méretének kiszámítása használatos az utolsó hozzáférés dátuma szerinti rendezéssel. A korlát túllépésekor a legrégebbi hozzáférési dátumú fájlok törlődnek, amíg a méret a korlát 50%-a alá nem csökken. A TTL tisztítás a gyorsítótár inicializálásakor és minden cleanExpired hívásakor történik.

Kingfisher használati példák Swift-ben

A Kingfisher több interfészt biztosít a képek betöltéséhez: kiterjesztés UIImageView-ra, külön kezelő és SwiftUI View.

Betöltés UIImageView-ban kf-en keresztül

kf — a namespace tulajdonság UIImageView-n, amely a setImage, cancelDownload metódusokat és betöltési jelzőket biztosít. A setImage metódus elfogadja a URLSource-t és opcionális Options paramétereket és completionHandler-t.

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("Betöltve \(receivedSize) / \(totalSize)")
    }
)

A metódus DownloadTask-et ad vissza, amely támogatja a megszakítást a cancel-en keresztül és a folyamat nyomon követését. Belsőleg a setImage meghívja a KingfisherManager.shared.retrieveImage-t az ImageView automatikus Target-ként való meghatározásával.

Használat async/await-tel

A Kingfisher 7.0-tól kezdve a setImage metódus elérhető aszinkron verzióban. Ez lehetővé teszi a képbetöltés integrálását a Swift Structured Concurrency-be callback-ek nélkül.

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

KFImage SwiftUI-hoz

KFImage — SwiftUI View, hasonló az iOS 15-beli AsyncImage-hez, de a Kingfisher gyorsítótárazásának teljes támogatásával. A View automatikusan a KingfisherManager.shared-t használja, de támogatja az egyéni kezelőt a .configure módosítón keresztül.

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

Betöltési jelzők a Kingfisher-ben

A Kingfisher beépített jelzőrendszert biztosít a képbetöltés előrehaladásának megjelenítéséhez. IndicatorType — egy felsorolás három változattal: .activity (UIActivityIndicatorView), .progress (UIProgressView) és .custom (az Indicator protokoll egyéni implementációja). A jelző automatikusan megjelenik az ImageView-n a betöltés során, és elrejtésre kerül a befejezés után.

Egyéni jelzőhöz az Indicator protokollt kell implementálni a startAnimatingView() és stopAnimatingView() metódusokkal. Ez lehetővé teszi hibrid megoldások használatát: csontváz shimmer animációval, helyettesítő kép fokozatos megjelenéssel vagy logó átlátszósági animációval. A Kingfisher támogatja a jelző globális beállítását is a KingfisherManager.shared.defaultOptions segítségével.

Kingfisher vs SDWebImage

Az iOS platformon a Kingfisher és az SDWebImage a két domináns képbetöltő könyvtár. A köztük lévő választás a projekt nyelvétől, a teljesítménykövetelményektől és az ökoszisztémától függ.

A Kingfisher legfőbb előnye a Swift-first architektúra: teljes támogatás az async/await, Combine Publishers, Sendable és Result típusok számára. Az SDWebImage megtartja vezető szerepét a szélesebb plugin ökoszisztémának (WebP, SVG, MapKit) és az Objective-C támogatásnak köszönhetően.

Kingfisher beállítása iOS projektben

A Kingfisher telepítése Swift Package Manager, CocoaPods vagy Carthage segítségével történik. Telepítés után elegendő a modul importálása és bármely betöltési metódus meghívása — a könyvtár készen áll a használatra további konfiguráció nélkül.

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

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

A globális beállítások testreszabásához a KingfisherManager.shared használható. Módosítható a betöltő időtúllépése, a gyorsítótár-stratégia és az alapértelmezett processzorok. Az alábbiakban egy 500 MB-os gyorsítótár konfigurációs példa látható 14 napos TTL-lel.

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

Az ImageDownloader szintén a kezelőn keresztül konfigurálható: egyéni URLSessionConfiguration állítható be időtúllépésekkel, fejlécekkel és gyorsítótár-irányelvekkel. A folyamat nyomon követéséhez a KFIndicator modul áll rendelkezésre ActivityIndicator, ProgressView és egyéni jelzők támogatásával.