Kingfisher — apa itu, konsep kunci dan ImageCache

Apa itu Kingfisher?

Kingfisher — library untuk memuat dan menyimpan cache gambar secara asinkron di platform Apple, ditulis sepenuhnya dalam Swift. Penulis library ini adalah Wei Wang (onevcat). Kingfisher menyediakan seperangkat alat untuk memuat gambar dari jaringan dengan caching otomatis, transformasi dan dukungan untuk teknologi Swift modern: async/await, Combine, Sendable.

Library ini memiliki lebih dari 23.000 bintang di GitHub dan digunakan di aplikasi seperti Telegram, Snapchat dan Dropbox. Kingfisher mendukung GIF, APNG, HEIF dan semua format gambar standar. Setiap permintaan mengembalikan Result yang aman tipe, menghilangkan kesalahan konversi tipe.

Arsitektur Kingfisher dibangun di atas tiga komponen utama: Manager (manajer pemuatan), Cache (cache dua tingkat) dan Processor (transformasi). Komponen-komponen ini terhubung melalui protokol, memungkinkan penggantian bagian mana pun tanpa mengubah dependensi.

Bagaimana Kingfisher bekerja: Manager dan Cache

KingfisherManager — kelas pusat yang mengoordinasikan pemuatan, caching dan pemrosesan gambar. Ini berisi referensi ke ImageCache dan ImageDownloader dan menyediakan metode terpadu retrieveImage yang mengembalikan gambar siap setelah melewati semua tahap.

Proses pemuatan

Saat retrieveImage dipanggil, Manager pertama-tama memeriksa Memory Cache — NSCache dengan UIImage, di mana kunci dibentuk dari URL sumber dan CacheSerializer. Jika gambar ditemukan — segera dikembalikan. Jika tidak ada, Disk Cache diperiksa — membaca dari sistem file dengan dekripsi melalui serializer. Jika cache di disk kosong, permintaan jaringan dijalankan melalui ImageDownloader, hasilnya didekode, ditransformasi dan disimpan di kedua tingkat cache.

• Memory Cache — berbasis NSCache, otomatis dibersihkan saat peringatan memori
• Disk Cache — penyimpanan file dengan TTL dan pemeriksaan batas ukuran
• ImageDownloader — berbasis URLSession dengan dukungan modifikasi permintaan melalui pengubah

Swift Concurrency

Mulai versi 7.0, Kingfisher sepenuhnya mendukung async/await. Metode retrieveImage tersedia sebagai fungsi asinkron yang mengembalikan Result secara langsung tanpa blok completion. Ini memungkinkan penggunaan library dalam arsitektur Swift modern dengan Structured Concurrency.

Modul utama Kingfisher

Kingfisher dibagi menjadi beberapa modul, masing-masing menyelesaikan tugasnya sendiri. Pembagian ini menyederhanakan pengujian dan penggantian komponen.

KingfisherManager

KingfisherManager — facade yang menggabungkan pemuatan, cache dan prosesor. Secara default, singleton KingfisherManager.shared digunakan, tetapi instance terpisah dengan pengaturan kustom dapat dibuat untuk skenario terisolasi (misalnya untuk pengujian unit).

ImageCache

ImageCache — cache dua tingkat dengan pengaturan terpisah untuk memori dan disk. Memory Cache tidak memiliki batasan jumlah objek, tetapi dibersihkan oleh sistem saat memori habis. Disk Cache menyimpan file di direktori dengan pengaturan TTL (default 7 hari), batas ukuran (default 0 — tanpa batas) dan pembersihan otomatis.

ImageProcessor

ImageProcessor — protokol dengan metode tunggal process(item:options:) yang mengembalikan gambar yang diproses. Implementasi bawaan: ResizingImageProcessor (ubah ukuran), RoundCornerImageProcessor (pembulatan), BlurImageProcessor (pengaburan Gaussian), OverlayImageProcessor (penambahan warna). Prosesor dapat digabungkan dengan operator |>.

Sistem caching Kingfisher

Arsitektur cache Kingfisher didasarkan pada prinsip write-through: data ditulis secara bersamaan di kedua tingkat, dan pembacaan dimulai dari tingkat tercepat — memori. Kunci cache adalah URL absolut gambar setelah menghapus parameter kueri.

Untuk mengelola ukuran Disk Cache, digunakan perhitungan total ukuran file dengan pengurutan berdasarkan tanggal akses terakhir. Saat batas terlampaui, file dengan tanggal akses tertua dihapus hingga ukuran turun di bawah 50% dari batas. Pembersihan TTL terjadi saat inisialisasi cache dan setiap panggilan cleanExpired.

Contoh penggunaan Kingfisher di Swift

Kingfisher menyediakan beberapa antarmuka untuk memuat gambar: ekstensi pada UIImageView, manajer terpisah dan SwiftUI View.

Memuat di UIImageView melalui kf

kf — properti namespace pada UIImageView yang menyediakan metode setImage, cancelDownload dan indikator pemuatan. Metode setImage menerima URLSource dan parameter opsional Options dan 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("Dimuat \(receivedSize) / \(totalSize)")
    }
)

Metode mengembalikan DownloadTask, yang mendukung pembatalan melalui cancel dan pelacakan kemajuan. Di dalamnya, setImage memanggil KingfisherManager.shared.retrieveImage dengan penentuan otomatis ImageView sebagai Target.

Penggunaan dengan async/await

Mulai Kingfisher 7.0, metode setImage tersedia dalam versi asinkron. Ini memungkinkan integrasi pemuatan gambar ke dalam Swift Structured Concurrency tanpa 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 berisi UIImage
    } catch {
        print("Gagal: \(error)")
    }
}

KFImage untuk SwiftUI

KFImage — SwiftUI View, mirip dengan AsyncImage dari iOS 15, tetapi dengan dukungan penuh caching Kingfisher. View secara otomatis menggunakan KingfisherManager.shared, tetapi mendukung manajer kustom melalui pengubah .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)
    }
}

Indikator pemuatan di Kingfisher

Kingfisher menyediakan sistem indikator bawaan untuk menampilkan kemajuan pemuatan gambar. IndicatorType — enumerasi dengan tiga varian: .activity (UIActivityIndicatorView), .progress (UIProgressView) dan .custom (implementasi kustom protokol Indicator). Indikator secara otomatis ditampilkan di ImageView selama pemuatan dan disembunyikan setelah selesai.

Untuk indikator kustom, protokol Indicator harus diimplementasikan dengan metode startAnimatingView() dan stopAnimatingView(). Ini memungkinkan penggunaan solusi hibrida: kerangka dengan animasi shimmer, gambar placeholder dengan kemunculan bertahap atau logo dengan animasi transparansi. Kingfisher juga mendukung pengaturan indikator secara global melalui KingfisherManager.shared.defaultOptions.

Kingfisher vs SDWebImage

Di platform iOS, Kingfisher dan SDWebImage adalah dua library dominan untuk pemuatan gambar. Pilihan di antara mereka tergantung pada bahasa proyek, persyaratan kinerja dan ekosistem.

Keunggulan utama Kingfisher adalah arsitektur Swift-first: dukungan penuh untuk async/await, Combine Publishers, Sendable dan tipe Result. SDWebImage mempertahankan kepemimpinan karena ekosistem plugin yang lebih luas (WebP, SVG, MapKit) dan dukungan Objective-C.

Menyiapkan Kingfisher di proyek iOS

Kingfisher diinstal melalui Swift Package Manager, CocoaPods atau Carthage. Setelah instalasi, cukup impor modul dan panggil metode pemuatan apa pun — library siap digunakan tanpa konfigurasi tambahan.

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

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

Untuk menyesuaikan pengaturan global, gunakan KingfisherManager.shared. Timeout loader, strategi cache dan prosesor default dapat diubah. Berikut adalah contoh konfigurasi cache 500 MB dengan TTL 14 hari.

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 juga dikonfigurasi melalui manajer: URLSessionConfiguration kustom dengan timeout, header dan kebijakan cache dapat diatur. Untuk memantau kemajuan, modul KFIndicator tersedia dengan dukungan ActivityIndicator, ProgressView dan indikator kustom.