Kingfisher — co to jest, kluczowe pojęcia i ImageCache

Czym jest Kingfisher?

Kingfisher — biblioteka do asynchronicznego ładowania i buforowania obrazów na platformach Apple, napisana w całości w Swift. Autorem biblioteki jest Wei Wang (onevcat). Kingfisher zapewnia zestaw narzędzi do ładowania obrazów z sieci z automatycznym buforowaniem, transformacjami i obsługą nowoczesnych technologii Swift: async/await, Combine, Sendable.

Biblioteka ma ponad 23 000 gwiazdek na GitHub i jest używana w takich aplikacjach jak Telegram, Snapchat i Dropbox. Kingfisher obsługuje GIF, APNG, HEIF oraz wszystkie standardowe formaty obrazów. Każde żądanie zwraca bezpieczny typowo Result, eliminujący błędy rzutowania typów.

Architektura Kingfisher opiera się na trzech głównych komponentach: Manager (menedżer pobierania), Cache (dwupoziomowa pamięć podręczna) i Processor (transformacje). Te komponenty są połączone za pomocą protokołów, co pozwala na wymianę dowolnej części bez zmiany zależności.

Jak działa Kingfisher: Manager i Cache

KingfisherManager — centralna klasa koordynująca ładowanie, buforowanie i przetwarzanie obrazów. Zawiera referencje do ImageCache i ImageDownloader oraz udostępnia jednolitą metodę retrieveImage, która zwraca gotowy obraz po przejściu wszystkich etapów.

Proces ładowania

Podczas wywołania retrieveImage Manager najpierw sprawdza Memory Cache — NSCache z UIImage, gdzie klucz jest tworzony z URL źródła i CacheSerializer. Jeśli obraz zostanie znaleziony — jest zwracany natychmiast. W przypadku braku sprawdzany jest Disk Cache — odczyt z systemu plików z deszyfracją przez serializer. Jeśli pamięć podręczna na dysku jest pusta — wykonywane jest żądanie sieciowe przez ImageDownloader, wynik jest dekodowany, transformowany i zapisywany w obu poziomach pamięci podręcznej.

• Memory Cache — oparty na NSCache, automatycznie czyszczony przy ostrzeżeniu o pamięci
• Disk Cache — przechowywanie plików z TTL i sprawdzaniem limitu rozmiaru
• ImageDownloader — oparty na URLSession z obsługą modyfikacji żądania przez modyfikatory

Swift Concurrency

Od wersji 7.0, Kingfisher w pełni obsługuje async/await. Metoda retrieveImage jest dostępna jako funkcja asynchroniczna, zwracająca Result bezpośrednio bez bloków completion. Pozwala to na używanie biblioteki w nowoczesnych architekturach Swift z Structured Concurrency.

Główne moduły Kingfisher

Kingfisher jest podzielona na kilka modułów, z których każdy rozwiązuje swoje zadanie. Taki podział ułatwia testowanie i wymianę komponentów.

KingfisherManager

KingfisherManager — fasada łącząca ładowanie, pamięć podręczną i procesory. Domyślnie używany jest singleton KingfisherManager.shared, ale można utworzyć osobną instancję z niestandardowymi ustawieniami dla izolowanych scenariuszy (np. do testów modułowych).

ImageCache

ImageCache — dwupoziomowa pamięć podręczna z oddzielnymi ustawieniami dla pamięci i dysku. Memory Cache nie ma ograniczenia liczby obiektów, ale jest czyszczona przez system przy braku pamięci. Disk Cache przechowuje pliki w katalogu z ustawieniami TTL (domyślnie 7 dni), limitem rozmiaru (domyślnie 0 — bez ograniczenia) i automatycznym czyszczeniem.

ImageProcessor

ImageProcessor — protokół z pojedynczą metodą process(item:options:), zwracającą przetworzony obraz. Wbudowane implementacje: ResizingImageProcessor (zmiana rozmiaru), RoundCornerImageProcessor (zaokrąglanie), BlurImageProcessor (rozmycie gaussowskie), OverlayImageProcessor (nakładanie koloru). Procesory można łączyć za pomocą operatora |>.

System buforowania Kingfisher

Architektura pamięci podręcznej Kingfisher opiera się na zasadzie write-through: dane są zapisywane jednocześnie na obu poziomach, a odczyt zaczyna się od najszybszego poziomu — pamięci. Kluczem pamięci podręcznej jest bezwzględny URL obrazu po usunięciu parametrów zapytania.

Do zarządzania rozmiarem Disk Cache używane jest obliczanie całkowitego rozmiaru plików z sortowaniem według daty ostatniego dostępu. Po przekroczeniu limitu usuwane są pliki z najstarszą datą dostępu, aż rozmiar spadnie poniżej 50% limitu. Czyszczenie TTL odbywa się przy inicjalizacji pamięci podręcznej i przy każdym wywołaniu cleanExpired.

Przykłady użycia Kingfisher w Swift

Kingfisher udostępnia kilka interfejsów do ładowania obrazów: rozszerzenie na UIImageView, osobny menedżer i SwiftUI View.

Ładowanie w UIImageView przez kf

kf — właściwość namespace na UIImageView, udostępniająca metody setImage, cancelDownload i wskaźniki ładowania. Metoda setImage przyjmuje URLSource i opcjonalne parametry Options oraz 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("Załadowano \(receivedSize) / \(totalSize)")
    }
)

Metoda zwraca DownloadTask, który obsługuje anulowanie przez cancel i śledzenie postępu. Wewnętrznie setImage wywołuje KingfisherManager.shared.retrieveImage z automatycznym określeniem ImageView jako Target.

Użycie z async/await

Od Kingfisher 7.0, metoda setImage jest dostępna w wersji asynchronicznej. Pozwala to na integrację ładowania obrazów z Swift Structured Concurrency bez callbacków.

func loadAvatar() async {
    do {
        let result = try await imageView.kf.setImage(
            with: url,
            options: [.processor(ResizingImageProcessor(
                targetSize: CGSize(width: 100, height: 100)
            ))]
        )
        // result.image zawiera UIImage
    } catch {
        print("Niepowodzenie: \(error)")
    }
}

KFImage dla SwiftUI

KFImage — SwiftUI View, analogiczna do AsyncImage z iOS 15, ale z pełną obsługą buforowania Kingfisher. View automatycznie używa KingfisherManager.shared, ale obsługuje niestandardowy menedżer przez modyfikator .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)
    }
}

Wskaźniki ładowania w Kingfisher

Kingfisher udostępnia wbudowany system wskaźników do wyświetlania postępu ładowania obrazu. IndicatorType — wyliczenie z trzema wariantami: .activity (UIActivityIndicatorView), .progress (UIProgressView) i .custom (niestandardowa implementacja protokołu Indicator). Wskaźnik jest automatycznie wyświetlany na ImageView podczas ładowania i ukrywany po zakończeniu.

Dla niestandardowego wskaźnika należy zaimplementować protokół Indicator z metodami startAnimatingView() i stopAnimatingView(). Pozwala to na stosowanie hybrydowych rozwiązań: skeleton z animacją shimmer, obraz zastępczy z stopniowym pojawianiem się lub logo z animacją przezroczystości. Kingfisher obsługuje również ustawienie wskaźnika globalnie przez KingfisherManager.shared.defaultOptions.

Kingfisher vs SDWebImage

Na platformie iOS Kingfisher i SDWebImage są dwiema dominującymi bibliotekami do ładowania obrazów. Wybór między nimi zależy od języka projektu, wymagań dotyczących wydajności i ekosystemu.

Kluczową zaletą Kingfisher jest Swift-first architektura: pełna obsługa async/await, Combine Publishers, Sendable i typów Result. SDWebImage zachowuje przewagę dzięki szerszemu ekosystemowi wtyczek (WebP, SVG, MapKit) i obsłudze Objective-C.

Konfiguracja Kingfisher w projekcie iOS

Kingfisher jest instalowany przez Swift Package Manager, CocoaPods lub Carthage. Po instalacji wystarczy zaimportować moduł i wywołać dowolną metodę ładowania — biblioteka jest gotowa do pracy bez dodatkowej konfiguracji.

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

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

Do dostosowania globalnych ustawień używany jest KingfisherManager.shared. Można zmienić timeout ładowarki, strategię pamięci podręcznej i domyślne procesory. Poniżej przykład konfiguracji pamięci podręcznej na 500 MB z TTL 14 dni.

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 jest również konfigurowany przez menedżer: można ustawić niestandardową URLSessionConfiguration z timeoutami, nagłówkami i politykami buforowania. Do monitorowania postępu dostępny jest moduł KFIndicator z obsługą ActivityIndicator, ProgressView i niestandardowych wskaźników.