Kingfisher — bu nədir, əsas anlayışlar və ImageCache

Kingfisher nədir?

Kingfisher — tamamilə Swift-də yazılmış Apple platformaları üçün asinxron şəkil yükləmə və keşləmə kitabxanası. Kitabxananın müəllifi Wei Wang (onevcat)-dir. Kingfisher şəbəkədən şəkillərin avtomatik keşləmə, transformasiya və müasir Swift texnologiyaları (async/await, Combine, Sendable) dəstəyi ilə yüklənməsi üçün alətlər dəsti təqdim edir.

Kitabxananın GitHub-da 23 000+ ulduzu var və Telegram, Snapchat və Dropbox kimi tətbiqlərdə istifadə olunur. Kingfisher GIF, APNG, HEIF və bütün standart şəkil formatlarını dəstəkləyir. Hər sorğu tip-təhlükəsiz Result qaytarır və tip çevirmə xətalarını aradan qaldırır.

Kingfisher-in arxitekturası üç əsas komponent üzərində qurulub: Manager (yükləmə meneceri), Cache (iki səviyyəli keş) və Processor (transformasiyalar). Bu komponentlər protokollar vasitəsilə bağlıdır ki, bu da asılılıqları dəyişmədən istənilən hissəni əvəz etməyə imkan verir.

Kingfisher necə işləyir: Manager və Cache

KingfisherManager — şəkillərin yüklənməsini, keşlənməsini və emalını koordinasiya edən mərkəzi sinif. O, ImageCache və ImageDownloader-ə istinadlar ehtiva edir və bütün mərhələlərdən keçdikdən sonra hazır şəkli qaytaran vahid retrieveImage metodunu təqdim edir.

Yükləmə prosesi

retrieveImage çağırıldıqda Manager əvvəlcə Memory Cache-i yoxlayır — açarın URL mənbəyi və CacheSerializer-dən formalaşdığı UIImage ilə NSCache. Şəkil tapılarsa — dərhal qaytarılır. Əgər tapılmazsa, Disk Cache yoxlanılır — serializer vasitəsilə deshifrələmə ilə fayl sistemindən oxuma. Disk keşi boşdursa, ImageDownloader vasitəsilə şəbəkə sorğusu yerinə yetirilir, nəticə dekodlanır, transformasiya olunur və hər iki keş səviyyəsində saxlanılır.

• Memory Cache — NSCache əsaslı, yaddaş xəbərdarlığında avtomatik təmizlənir
• Disk Cache — TTL və ölçü limiti yoxlaması ilə fayl anbarı
• ImageDownloader — modifikatorlar vasitəsilə sorğu dəyişikliyi dəstəyi ilə URLSession əsaslı

Swift Concurrency

7.0 versiyasından etibarən Kingfisher async/await-i tam dəstəkləyir. retrieveImage metodu completion blokları olmadan birbaşa Result qaytaran asinxron funksiya kimi mövcuddur. Bu, kitabxanadan Structured Concurrency ilə müasir Swift arxitekturalarında istifadə etməyə imkan verir.

Kingfisher-in əsas modulları

Kingfisher bir neçə modula bölünüb, hər biri öz vəzifəsini həll edir. Bu bölgü komponentlərin test edilməsini və dəyişdirilməsini asanlaşdırır.

KingfisherManager

KingfisherManager — yükləmə, keş və prosessorları birləşdirən fasad. Susmaya görə KingfisherManager.shared sinqltonu istifadə olunur, lakin təcrid olunmuş ssenarilər (məsələn, modul testləri üçün) fərdi parametrlərlə ayrıca nümunə yaradıla bilər.

ImageCache

ImageCache — yaddaş və disk üçün ayrıca parametrlərlə iki səviyyəli keş. Memory Cache obyektlərin sayına görə məhdudiyyətə malik deyil, lakin yaddaş çatışmazlığı zamanı sistem tərəfindən təmizlənir. Disk Cache faylları TTL (susmaya görə 7 gün), ölçü limiti (susmaya görə 0 — məhdudiyyətsiz) və avtomatik təmizləmə ilə kataloqda saxlayır.

ImageProcessor

ImageProcessor — emal edilmiş şəkli qaytaran tək process(item:options:) metodu olan protokol. Daxili tətbiqlər: ResizingImageProcessor (ölçü dəyişdirmə), RoundCornerImageProcessor (yumrulaşdırma), BlurImageProcessor (Qauss bulanıqlığı), OverlayImageProcessor (rəng əlavə etmə). Prosesorlar |> operatoru ilə birləşdirilə bilər.

Kingfisher keş sistemi

Kingfisher keş arxitekturası write-through prinsipi əsasında qurulub: məlumatlar eyni vaxtda hər iki səviyyədə yazılır, oxuma isə ən sürətli səviyyədən — yaddaşdan başlayır. Keş açarı sorğu parametrləri silindikdən sonra şəklin mütləq URL-idir.

Disk Cache ölçüsünü idarə etmək üçün son giriş tarixinə görə çeşidləmə ilə faylların ümumi ölçüsünün hesablanması istifadə olunur. Limit aşıldıqda, ölçü limitin 50%-dən aşağı düşənə qədər ən köhnə giriş tarixi olan fayllar silinir. TTL təmizlənməsi keşin işə salınması və hər cleanExpired çağırışında baş verir.

Swift-də Kingfisher istifadə nümunələri

Kingfisher şəkilləri yükləmək üçün bir neçə interfeys təqdim edir: UIImageView-də extension, ayrıca menecer və SwiftUI View.

UIImageView-də kf vasitəsilə yükləmə

kf — UIImageView-də setImage, cancelDownload və yükləmə göstəriciləri metodlarını təqdim edən namespace xüsusiyyəti. setImage metodu URLSource və isteğe bağlı Options parametrləri və completionHandler qəbul edir.

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ükləndi \(receivedSize) / \(totalSize)")
    }
)

Metod cancel ilə ləğvetmə və gedişatı izləməyi dəstəkləyən DownloadTask qaytarır. Daxildə setImage avtomatik ImageView-i Target kimi təyin etməklə KingfisherManager.shared.retrieveImage-i çağırır.

async/await ilə istifadə

Kingfisher 7.0-dan etibarən setImage metodu asinxron versiyada mövcuddur. Bu, callbacklər olmadan Swift Structured Concurrency-də şəkil yükləməni inteqrasiya etməyə imkan verir.

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 ehtiva edir
    } catch {
        print("Uğursuz oldu: \(error)")
    }
}

SwiftUI üçün KFImage

KFImage — iOS 15-dən AsyncImage-ə bənzər, lakin Kingfisher keşləməsinin tam dəstəyi ilə SwiftUI View. View avtomatik olaraq KingfisherManager.shared istifadə edir, lakin .configure modifieri vasitəsilə fərdi meneceri dəstəkləyir.

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-də yükləmə göstəriciləri

Kingfisher şəkil yükləmə gedişatını göstərmək üçün daxili göstərici sistemi təqdim edir. IndicatorType — üç variantlı sadalama: .activity (UIActivityIndicatorView), .progress (UIProgressView) və .custom (Indicator protokolunun fərdi tətbiqi). Göstərici yükləmə zamanı avtomatik olaraq ImageView üzərində göstərilir və tamamlandıqdan sonra gizlənir.

Fərdi göstərici üçün startAnimatingView() və stopAnimatingView() metodları ilə Indicator protokolunu tətbiq etmək lazımdır. Bu, hibrid həllərdən istifadə etməyə imkan verir: shimmer animasiyası ilə skeleton, tədricən görünmə ilə ehtiyat şəkil və ya şəffaflıq animasiyası ilə loqo. Kingfisher həmçinin KingfisherManager.shared.defaultOptions vasitəsilə göstəricinin qlobal quraşdırılmasını dəstəkləyir.

Kingfisher vs SDWebImage

iOS platformasında Kingfisher və SDWebImage şəkil yükləmə üçün iki dominant kitabxanadır. Onlar arasında seçim layihənin dilindən, performans tələblərindən və ekosistemdən asılıdır.

Kingfisher-in əsas üstünlüyü Swift-first arxitekturasıdır: async/await, Combine Publishers, Sendable və Result tiplərinin tam dəstəyi. SDWebImage daha geniş plagin ekosistemi (WebP, SVG, MapKit) və Objective-C dəstəyi hesabına liderliyini qoruyur.

iOS layihəsində Kingfisher-in qurulması

Kingfisher Swift Package Manager, CocoaPods və ya Carthage vasitəsilə quraşdırılır. Quraşdırmadan sonra modulu import etmək və istənilən yükləmə metodunu çağırmaq kifayətdir — kitabxana əlavə konfiqurasiya olmadan işə 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'

Qlobal parametrləri fərdiləşdirmək üçün KingfisherManager.shared istifadə olunur. Yükləyicinin timeout-u, keş strategiyası və susmaya görə prosessorlar dəyişdirilə bilər. Aşağıda 14 gün TTL ilə 500 MB keş konfiqurasiyası nümunəsi verilmişdir.

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 də menecer vasitəsilə konfiqurasiya olunur: timeoutlar, başlıqlar və keş siyasətləri ilə fərdi URLSessionConfiguration təyin etmək olar. Gedişatı izləmək üçün ActivityIndicator, ProgressView və fərdi göstəriciləri dəstəkləyən KFIndicator modulu mövcuddur.