Kingfisher — nedir, temel kavramlar ve ImageCache

Kingfisher nedir?

Kingfisher, Apple platformlarında asenkron görsel yükleme ve önbellekleme için tamamen Swift ile yazılmış bir kütüphanedir. Kütüphanenin yazarı Wei Wang'dır (onevcat). Kingfisher, otomatik önbellekleme, dönüşümler ve modern Swift teknolojileri (async/await, Combine, Sendable) desteği ile ağdan görsel yüklemek için bir araç seti sağlar.

Kütüphane GitHub'da 23.000'den fazla yıldıza sahiptir ve Telegram, Snapchat ve Dropbox gibi uygulamalarda kullanılır. Kingfisher, GIF, APNG, HEIF ve tüm standart görsel formatlarını destekler. Her istek, tip dönüştürme hatalarını ortadan kaldıran tip güvenli bir Result döndürür.

Kingfisher'ın mimarisi üç ana bileşen üzerine kurulmuştur: Manager (indirme yöneticisi), Cache (iki seviyeli önbellek) ve Processor (dönüşümler). Bu bileşenler protokoller aracılığıyla bağlanır ve bağımlılıkları değiştirmeden herhangi bir parçanın değiştirilmesine olanak tanır.

Kingfisher nasıl çalışır: Manager ve Cache

KingfisherManager, görsel yükleme, önbellekleme ve işlemeyi koordine eden merkezi sınıftır. ImageCache ve ImageDownloader'a referanslar içerir ve tüm aşamalardan geçtikten sonra hazır görseli döndüren tek bir retrieveImage yöntemi sağlar.

Yükleme süreci

retrieveImage çağrıldığında, Manager önce Memory Cache'i kontrol eder — anahtarın kaynak URL ve CacheSerializer'dan oluşturulduğu UIImage ile bir NSCache. Görsel bulunursa hemen döndürülür. Bulunamazsa, Disk Cache kontrol edilir — serileştirici aracılığıyla şifre çözme ile dosya sisteminden okuma. Disk önbelleği boşsa, ImageDownloader aracılığıyla bir ağ isteği yapılır, sonuç çözülür, dönüştürülür ve her iki önbellek seviyesine kaydedilir.

• Memory Cache — NSCache tabanlı, bellek uyarısında otomatik olarak temizlenir
• Disk Cache — TTL ve boyut sınırı kontrolü ile dosya depolama
• ImageDownloader — değiştiriciler aracılığıyla istek değişikliği desteği ile URLSession tabanlı

Swift Concurrency

Sürüm 7.0'dan itibaren Kingfisher, async/await'i tam olarak destekler. retrieveImage yöntemi, tamamlama blokları olmadan doğrudan Result döndüren asenkron bir işlev olarak kullanılabilir. Bu, Structured Concurrency ile modern Swift mimarilerinde kütüphanenin kullanılmasına olanak tanır.

Kingfisher'ın temel modülleri

Kingfisher, her biri kendi görevini çözen birkaç modüle ayrılmıştır. Bu ayrım, test etmeyi ve bileşen değiştirmeyi kolaylaştırır.

KingfisherManager

KingfisherManager, yükleme, önbellek ve işlemcileri birleştiren bir cephedir. Varsayılan olarak, KingfisherManager.shared singleton'ı kullanılır, ancak izole senaryolar için (örneğin, birim testleri için) özel ayarlarla ayrı bir örnek oluşturulabilir.

ImageCache

ImageCache, bellek ve disk için ayrı ayarlarla iki seviyeli bir önbellektir. Memory Cache'in nesne sayısında bir sınırı yoktur, ancak bellek azaldığında sistem tarafından temizlenir. Disk Cache, yapılandırılabilir TTL (varsayılan 7 gün), boyut sınırı (varsayılan 0 — sınır yok) ve otomatik temizleme ile bir dizinde dosyaları saklar.

ImageProcessor

ImageProcessor, işlenmiş görseli döndüren tek bir process(item:options:) yöntemine sahip bir protokoldür. Yerleşik uygulamalar: ResizingImageProcessor (boyutlandırma), RoundCornerImageProcessor (yuvarlama), BlurImageProcessor (Gauss bulanıklığı), OverlayImageProcessor (renk yerleşimi). İşlemciler |> operatörü kullanılarak birleştirilebilir.

Kingfisher önbellek sistemi

Kingfisher önbellek mimarisi write-through ilkesine dayanır: veriler her iki seviyeye aynı anda yazılır ve okuma en hızlı seviyeden — bellekten başlar. Önbellek anahtarı, sorgu parametreleri kaldırıldıktan sonraki mutlak görsel URL'sidir.

Disk Cache boyutunu yönetmek için, son erişim tarihine göre sıralanarak dosyaların toplam boyutu hesaplanır. Sınır aşıldığında, boyut sınırın %50'sinin altına düşene kadar en eski erişim tarihine sahip dosyalar kaldırılır. TTL temizliği, önbellek başlatma sırasında ve her cleanExpired çağrısında gerçekleşir.

Swift'te Kingfisher kullanım örnekleri

Kingfisher, görsel yüklemek için birkaç arayüz sağlar: UIImageView üzerinde bir uzantı, ayrı bir yönetici ve bir SwiftUI View.

UIImageView'de kf ile yükleme

kf, UIImageView üzerinde setImage, cancelDownload yöntemlerini ve yükleme göstergelerini sağlayan bir ad alanı özelliğidir. setImage yöntemi, URLSource ve isteğe bağlı Options ve completionHandler parametrelerini kabul eder.

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("Yüklendi \(receivedSize) / \(totalSize)")
    }
)

Yöntem, cancel ile iptal ve ilerleme takibini destekleyen bir DownloadTask döndürür. Dahili olarak, setImage, ImageView'ı Target olarak otomatik algılama ile KingfisherManager.shared.retrieveImage'ı çağırır.

async/await ile kullanım

Kingfisher 7.0'dan itibaren, setImage yöntemi asenkron bir sürümde kullanılabilir. Bu, geri aramalar olmadan Swift Structured Concurrency'ye görsel yüklemeyi entegre etmeye olanak tanır.

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 içeriyor
    } catch {
        print("Başarısız: \(error)")
    }
}

SwiftUI için KFImage

KFImage, iOS 15'teki AsyncImage'e benzer, ancak tam Kingfisher önbellek desteği ile bir SwiftUI View'dır. View, otomatik olarak KingfisherManager.shared kullanır ancak .configure değiştiricisi aracılığıyla özel bir yöneticiyi destekler.

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'da yükleme göstergeleri

Kingfisher, görsel yükleme ilerlemesini görüntülemek için yerleşik bir gösterge sistemi sağlar. IndicatorType, üç seçeneği olan bir numaralandırmadır: .activity (UIActivityIndicatorView), .progress (UIProgressView) ve .custom (Indicator protokolünün özel uygulaması). Gösterge, yükleme sırasında ImageView'ın üzerinde otomatik olarak görünür ve tamamlandıktan sonra gizlenir.

Özel bir gösterge için, startAnimatingView() ve stopAnimatingView() yöntemleriyle Indicator protokolünü uygulamak gerekir. Bu, parıltı animasyonlu iskelet, kademeli açığa çıkmalı yer tutucu görsel veya opaklık animasyonlu logo gibi hibrit çözümlere olanak tanır. Kingfisher ayrıca KingfisherManager.shared.defaultOptions aracılığıyla göstergenin genel olarak ayarlanmasını da destekler.

Kingfisher vs SDWebImage

iOS platformunda, Kingfisher ve SDWebImage, görsel yükleme için iki baskın kütüphanedir. Aralarındaki seçim, proje diline, performans gereksinimlerine ve ekosisteme bağlıdır.

Kingfisher'ın temel avantajı Swift-first mimarisidir: async/await, Combine Publishers, Sendable ve Result türleri için tam destek. SDWebImage, daha geniş eklenti ekosistemi (WebP, SVG, MapKit) ve Objective-C desteği sayesinde liderliğini sürdürmektedir.

iOS projesinde Kingfisher kurulumu

Kingfisher, Swift Package Manager, CocoaPods veya Carthage aracılığıyla kurulur. Kurulumdan sonra, modülü içe aktarmak ve herhangi bir yükleme yöntemini çağırmak yeterlidir — kütüphane ek yapılandırma olmadan kullanıma hazırdır.

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

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

Küresel ayarları özelleştirmek için KingfisherManager.shared kullanılır. İndirici zaman aşımı, önbellek stratejisi ve varsayılan işlemciler değiştirilebilir. Aşağıda, 14 günlük TTL ile 500 MB'lık bir önbellek yapılandırma örneği verilmiştir.

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 da yönetici aracılığıyla yapılandırılır: zaman aşımları, başlıklar ve önbellek politikaları ile özel bir URLSessionConfiguration ayarlanabilir. İlerlemeyi izlemek için, ActivityIndicator, ProgressView ve özel göstergeleri destekleyen KFIndicator modülü mevcuttur.