Kingfisher — ano ito, mga pangunahing konsepto at ImageCache

Ano ang Kingfisher?

Kingfisher — isang library para sa asynchronous na pag-load at pag-cache ng mga larawan sa mga platform ng Apple, na ganap na nakasulat sa Swift. Ang may-akda ng library ay si Wei Wang (onevcat). Ang Kingfisher ay nagbibigay ng isang hanay ng mga tool para sa pag-load ng mga larawan mula sa network na may awtomatikong pag-cache, mga pagbabago at suporta para sa mga modernong teknolohiya ng Swift: async/await, Combine, Sendable.

Ang library ay may higit sa 23,000 bituin sa GitHub at ginagamit sa mga application tulad ng Telegram, Snapchat at Dropbox. Ang Kingfisher ay sumusuporta sa GIF, APNG, HEIF at lahat ng karaniwang format ng larawan. Ang bawat kahilingan ay nagbabalik ng isang type-safe na Result, na nag-aalis ng mga error sa conversion ng uri.

Ang arkitektura ng Kingfisher ay binuo sa tatlong pangunahing bahagi: Manager (manager ng pag-load), Cache (dalawang antas na cache) at Processor (mga pagbabago). Ang mga bahaging ito ay konektado sa pamamagitan ng mga protocol, na nagpapahintulot sa pagpapalit ng anumang bahagi nang hindi binabago ang mga dependency.

Paano gumagana ang Kingfisher: Manager at Cache

KingfisherManager — ang sentral na klase na nagko-coordinate ng pag-load, pag-cache at pagproseso ng mga larawan. Naglalaman ito ng mga sanggunian sa ImageCache at ImageDownloader at nagbibigay ng pinag-isang pamamaraan na retrieveImage na nagbabalik ng handa na larawan pagkatapos dumaan sa lahat ng yugto.

Proseso ng pag-load

Kapag tinawag ang retrieveImage, una munang sinusuri ng Manager ang Memory Cache — NSCache na may UIImage, kung saan ang susi ay nabuo mula sa URL ng pinagmulan at CacheSerializer. Kung ang larawan ay natagpuan — ito ay agad na ibabalik. Kung hindi, sinusuri ang Disk Cache — pagbabasa mula sa file system na may pag-decrypt sa pamamagitan ng serializer. Kung ang cache sa disk ay walang laman, ang isang kahilingan sa network ay isasagawa sa pamamagitan ng ImageDownloader, ang resulta ay nade-decode, binabago at nai-save sa parehong antas ng cache.

• Memory Cache — batay sa NSCache, awtomatikong nililinis sa babala ng memorya
• Disk Cache — imbakan ng file na may TTL at pagsusuri ng limitasyon sa laki
• ImageDownloader — batay sa URLSession na may suporta para sa pagbabago ng kahilingan sa pamamagitan ng mga modifier

Swift Concurrency

Mula sa bersyon 7.0, ganap na sinusuportahan ng Kingfisher ang async/await. Ang pamamaraang retrieveImage ay magagamit bilang isang asynchronous na function na direktang nagbabalik ng Result nang walang mga bloke ng completion. Pinapayagan nito ang paggamit ng library sa mga modernong arkitektura ng Swift na may Structured Concurrency.

Mga pangunahing module ng Kingfisher

Ang Kingfisher ay nahahati sa ilang mga module, bawat isa ay gumaganap ng sarili nitong gawain. Ang paghahati na ito ay nagpapadali sa pagsubok at pagpapalit ng mga bahagi.

KingfisherManager

KingfisherManager — isang facade na pinagsasama ang pag-load, cache at mga processor. Bilang default, ginagamit ang singleton KingfisherManager.shared, ngunit ang isang hiwalay na instance ay maaaring gawin gamit ang mga custom na setting para sa mga nakahiwalay na sitwasyon (halimbawa, para sa mga unit test).

ImageCache

ImageCache — dalawang antas na cache na may hiwalay na mga setting para sa memorya at disk. Ang Memory Cache ay walang limitasyon sa bilang ng mga bagay, ngunit nililinis ng system kapag kulang ang memorya. Ang Disk Cache ay nag-iimbak ng mga file sa isang direktoryo na may mga setting ng TTL (default 7 araw), limitasyon sa laki (default 0 — walang limitasyon) at awtomatikong paglilinis.

ImageProcessor

ImageProcessor — protocol na may iisang pamamaraan na process(item:options:) na nagbabalik ng naprosesong larawan. Mga built-in na implementasyon: ResizingImageProcessor (pagbabago ng laki), RoundCornerImageProcessor (pag-round), BlurImageProcessor (Gaussian blur), OverlayImageProcessor (pagdagdag ng kulay). Ang mga processor ay maaaring pagsamahin gamit ang operator |>.

Sistema ng pag-cache ng Kingfisher

Ang arkitektura ng cache ng Kingfisher ay batay sa prinsipyo ng write-through: ang data ay isinusulat nang sabay-sabay sa parehong antas, at ang pagbabasa ay nagsisimula sa pinakamabilis na antas — memorya. Ang susi ng cache ay ang ganap na URL ng larawan pagkatapos alisin ang mga parameter ng query.

Para sa pamamahala ng laki ng Disk Cache, ginagamit ang pagkalkula ng kabuuang laki ng file na may pag-uuri ayon sa petsa ng huling pag-access. Kapag lumampas sa limitasyon, ang mga file na may pinakamatandang petsa ng pag-access ay tatanggalin hanggang ang laki ay bumaba sa ibaba 50% ng limitasyon. Ang paglilinis ng TTL ay nangyayari sa pagsisimula ng cache at sa bawat tawag sa cleanExpired.

Mga halimbawa ng paggamit ng Kingfisher sa Swift

Ang Kingfisher ay nagbibigay ng ilang mga interface para sa pag-load ng mga larawan: extension sa UIImageView, hiwalay na manager at SwiftUI View.

Pag-load sa UIImageView sa pamamagitan ng kf

kf — ang namespace property sa UIImageView na nagbibigay ng mga pamamaraang setImage, cancelDownload at mga indicator ng pag-load. Ang pamamaraang setImage ay tumatanggap ng URLSource at opsyonal na mga parameter na Options at 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-load \(receivedSize) / \(totalSize)")
    }
)

Ang pamamaraan ay nagbabalik ng DownloadTask, na sumusuporta sa pagkansela sa pamamagitan ng cancel at pagsubaybay sa progreso. Sa loob, ang setImage ay tumatawag sa KingfisherManager.shared.retrieveImage na may awtomatikong pagtukoy ng ImageView bilang Target.

Paggamit sa async/await

Mula sa Kingfisher 7.0, ang pamamaraang setImage ay magagamit sa asynchronous na bersyon. Pinapayagan nito ang pagsasama ng pag-load ng larawan sa Swift Structured Concurrency nang walang mga 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 ay naglalaman ng UIImage
    } catch {
        print("Nabigo: \(error)")
    }
}

KFImage para sa SwiftUI

KFImage — SwiftUI View, katulad ng AsyncImage mula sa iOS 15, ngunit may buong suporta para sa Kingfisher caching. Ang View ay awtomatikong gumagamit ng KingfisherManager.shared, ngunit sumusuporta sa custom na manager sa pamamagitan ng .configure modifier.

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

Mga indicator ng pag-load sa Kingfisher

Ang Kingfisher ay nagbibigay ng built-in na sistema ng indicator para sa pagpapakita ng progreso ng pag-load ng larawan. IndicatorType — isang enumeration na may tatlong variant: .activity (UIActivityIndicatorView), .progress (UIProgressView) at .custom (custom na implementasyon ng protocol na Indicator). Ang indicator ay awtomatikong ipinapakita sa ImageView sa panahon ng pag-load at itinatago pagkatapos makumpleto.

Para sa custom na indicator, ang protocol na Indicator ay dapat na ipatupad gamit ang mga pamamaraang startAnimatingView() at stopAnimatingView(). Pinapayagan nito ang paggamit ng mga hybrid na solusyon: skeleton na may shimmer animation, placeholder na larawan na may unti-unting paglitaw o logo na may transparency animation. Ang Kingfisher ay sumusuporta rin sa pandaigdigang pagtatakda ng indicator sa pamamagitan ng KingfisherManager.shared.defaultOptions.

Kingfisher vs SDWebImage

Sa platform ng iOS, ang Kingfisher at SDWebImage ay ang dalawang nangingibabaw na library para sa pag-load ng larawan. Ang pagpili sa pagitan ng mga ito ay depende sa wika ng proyekto, mga kinakailangan sa pagganap at ekosistema.

Ang pangunahing bentahe ng Kingfisher ay ang Swift-first na arkitektura: buong suporta para sa async/await, Combine Publishers, Sendable at Result na mga uri. Ang SDWebImage ay nagpapanatili ng pamumuno dahil sa mas malawak na ekosistema ng plugin (WebP, SVG, MapKit) at suporta para sa Objective-C.

Pag-setup ng Kingfisher sa proyekto ng iOS

Ang Kingfisher ay naka-install sa pamamagitan ng Swift Package Manager, CocoaPods o Carthage. Pagkatapos ng pag-install, sapat na upang i-import ang module at tawagan ang anumang pamamaraan ng pag-load — ang library ay handa nang gamitin nang walang karagdagang pagsasaayos.

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

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

Para sa pag-customize ng mga pandaigdigang setting, ginagamit ang KingfisherManager.shared. Ang timeout ng loader, diskarte sa cache at mga default na processor ay maaaring baguhin. Nasa ibaba ang isang halimbawa ng pagsasaayos ng cache na 500 MB na may TTL na 14 na araw.

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

Ang ImageDownloader ay naka-configure din sa pamamagitan ng manager: isang custom na URLSessionConfiguration na may mga timeout, header at mga patakaran sa cache ay maaaring itakda. Para sa pagsubaybay sa progreso, ang module na KFIndicator ay magagamit na may suporta para sa ActivityIndicator, ProgressView at mga custom na indicator.