Kingfisher — шта је то, кључни појмови и ImageCache

Шта је Kingfisher?

Kingfisher — библиотека за асинхроно учитавање и кеширање слика на Apple платформама, написана у потпуности у Swift-у. Аутор библиотеке је Wei Wang (onevcat). Kingfisher пружа скуп алата за учитавање слика из мреже са аутоматским кеширањем, трансформацијама и подршком за модерне Swift технологије: async/await, Combine, Sendable.

Библиотека има преко 23 000 звездица на GitHub-у и користи се у апликацијама попут Telegram-а, Snapchat-а и Dropbox-а. Kingfisher подржава GIF, APNG, HEIF и све стандардне формате слика. Сваки захтев враћа типно безбедан Result, који елиминише грешке при конверзији типова.

Архитектура Kingfisher-а је изграђена на три главне компоненте: Manager (менаџер учитавања), Cache (двонивоски кеш) и Processor (трансформације). Ове компоненте су повезане преко протокола, што омогућава замену било ког дела без мењања зависности.

Како ради Kingfisher: Manager и Cache

KingfisherManager — централна класа која координира учитавање, кеширање и обраду слика. Садржи референце на ImageCache и ImageDownloader и пружа јединствену методу retrieveImage која враћа спремну слику након проласка кроз све фазе.

Процес учитавања

При позиву retrieveImage, Manager прво проверава Memory Cache — NSCache са UIImage, где се кључ формира из URL-а извора и CacheSerializer-а. Ако је слика пронађена — враћа се одмах. Ако није, проверава се Disk Cache — читање из датотечног система са дешифровањем путем serializer-а. Ако је кеш на диску празан, извршава се мрежни захтев преко ImageDownloader-а, резултат се декодира, трансформише и чува на оба нивоа кеша.

• Memory Cache — заснован на NSCache, аутоматски се чисти при упозорењу о меморији
• Disk Cache — складиштење датотека са TTL-ом и провером границе величине
• ImageDownloader — заснован на URLSession-у са подршком за модификацију захтева преко модификатора

Swift Concurrency

Од верзије 7.0, Kingfisher у потпуности подржава async/await. Метода retrieveImage је доступна као асинхрона функција која враћа Result директно без completion блокова. Ово омогућава коришћење библиотеке у модерним Swift архитектурама са Structured Concurrency.

Главни модули Kingfisher-а

Kingfisher је подељена на неколико модула, од којих сваки решава свој задатак. Ова подела поједностављује тестирање и замену компоненти.

KingfisherManager

KingfisherManager — фасада која обједињује учитавање, кеш и процесоре. Подразумевано се користи синглтон KingfisherManager.shared, али се може креирати засебна инстанца са прилагођеним подешавањима за изоловане сценарије (нпр. за модуларне тестове).

ImageCache

ImageCache — двонивоски кеш са одвојеним подешавањима за меморију и диск. Memory Cache нема ограничење броја објеката, али га систем чисти при недостатку меморије. Disk Cache чува датотеке у директоријуму са подешавањима TTL-а (подразумевано 7 дана), границом величине (подразумевано 0 — без ограничења) и аутоматским чишћењем.

ImageProcessor

ImageProcessor — протокол са јединственом методом process(item:options:) која враћа обрађену слику. Уграђене имплементације: ResizingImageProcessor (промена величине), RoundCornerImageProcessor (заобљавање), BlurImageProcessor (Гаусово замућење), OverlayImageProcessor (наношење боје). Процесори се могу комбиновати преко оператора |>.

Систем кеширања Kingfisher-а

Архитектура кеша Kingfisher-а заснива се на принципу write-through: подаци се истовремено уписују на оба нивоа, а читање почиње од најбржег нивоа — меморије. Кључ кеша је апсолутни URL слике након уклањања query параметара.

За управљање величином Disk Cache-а користи се израчунавање укупне величине датотека са сортирањем по датуму последњег приступа. При прекорачењу границе, датотеке са најстаријим датумом приступа се бришу док величина не падне испод 50% границе. TTL чишћење се дешава при иницијализацији кеша и при сваком позиву cleanExpired.

Примери употребе Kingfisher-а у Swift-у

Kingfisher пружа неколико интерфејса за учитавање слика: проширење на UIImageView, засебан менаџер и SwiftUI View.

Учитавање у UIImageView преко kf

kf — namespace својство на UIImageView-у које пружа методе setImage, cancelDownload и индикаторе учитавања. Метода setImage прихвата URLSource и опционе параметре Options и 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("Учитано \(receivedSize) / \(totalSize)")
    }
)

Метода враћа DownloadTask, који подржава отказивање преко cancel и праћење напретка. Унутра, setImage позива KingfisherManager.shared.retrieveImage са аутоматским одређивањем ImageView-а као Target.

Коришћење са async/await

Од Kingfisher 7.0, метода setImage је доступна у асинхроној верзији. Ово омогућава интеграцију учитавања слика у Swift Structured Concurrency без 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 садржи UIImage
    } catch {
        print("Неуспешно: \(error)")
    }
}

KFImage за SwiftUI

KFImage — SwiftUI View, слична AsyncImage из iOS 15, али са пуном подршком за кеширање Kingfisher-а. View аутоматски користи KingfisherManager.shared, али подржава прилагођени менаџер преко модификатора .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)
    }
}

Индикатори учитавања у Kingfisher-у

Kingfisher пружа уграђени систем индикатора за приказ напретка учитавања слике. IndicatorType — набрајање са три варијанте: .activity (UIActivityIndicatorView), .progress (UIProgressView) и .custom (прилагођена имплементација протокола Indicator). Индикатор се аутоматски приказује на ImageView-у током учитавања и скрива након завршетка.

За прилагођени индикатор потребно је имплементирати протокол Indicator са методама startAnimatingView() и stopAnimatingView(). Ово омогућава коришћење хибридних решења: скелетон са shimmer анимацијом, слику-замену са постепеним појављивањем или лого са анимацијом провидности. Kingfisher такође подржава глобално подешавање индикатора преко KingfisherManager.shared.defaultOptions.

Kingfisher vs SDWebImage

На iOS платформи, Kingfisher и SDWebImage су две доминантне библиотеке за учитавање слика. Избор између њих зависи од језика пројекта, захтева за перформансама и екосистема.

Кључна предност Kingfisher-а је Swift-first архитектура: пуна подршка за async/await, Combine Publishers, Sendable и Result типове. SDWebImage задржава лидерство захваљујући ширим екосистему додатака (WebP, SVG, MapKit) и подршци за Objective-C.

Подешавање Kingfisher-а у iOS пројекту

Kingfisher се инсталира преко Swift Package Manager-а, CocoaPods-а или Carthage-а. Након инсталације, довољно је импортовати модул и позвати било коју методу учитавања — библиотека је спремна за рад без додатне конфигурације.

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

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

За прилагођавање глобалних подешавања користи се KingfisherManager.shared. Могуће је променити timeout учитавача, стратегију кеша и подразумеване процесоре. Испод је пример конфигурације кеша од 500 MB са TTL-ом од 14 дана.

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 се такође конфигурише преко менаџера: може се поставити прилагођена URLSessionConfiguration са timeouts, заглављима и политикама кеширања. За праћење напретка доступан је модул KFIndicator са подршком за ActivityIndicator, ProgressView и прилагођене индикаторе.