SDWebImage: co to jest, kluczowe pojęcia i UIImageView

Co to jest SDWebImage?

SDWebImage — biblioteka do asynchronicznego ładowania obrazów na platformach Apple (iOS, macOS, tvOS, watchOS). Udostępnia kategorię dla UIImageView z metodą sd_setImage, która jednym wierszem ładuje, buforuje i wyświetla obraz z dowolnego źródła.

Biblioteka obsługuje progresywne ładowanie (obraz jest wyświetlany w miarę otrzymywania bajtów), animowane obrazy (GIF, APNG), transformacje (zaokrąglanie, przycinanie, nakładanie znaku wodnego) i niestandardowe dekodery. Według GitHub Stats, SDWebImage ma ponad 25 tysięcy gwiazdek i jest używany w dużych aplikacjach, w tym Twitter, Pinterest i Instagram.

Architektura opiera się na łańcuchu komponentów: Coder (dekodowanie), Cache (przechowywanie), Loader (sieć) i Transformer (przetwarzanie). Każdy komponent jest wymienny, co pozwala dostosować bibliotekę do specyficznych wymagań projektu.

Jak działa SDWebImage: menedżer i pamięć podręczna

SDWebImageManager — centralny komponent koordynujący proces ładowania. Przyjmuje URL, sprawdza pamięć podręczną, ładuje dane, dekoduje je do UIImage i przekazuje do ImageView lub Completion Handler. Menedżer działa przez singleton shared, dostępny z każdego miejsca w aplikacji.

Proces ładowania

Menedżer kolejno sprawdza Memory Cache (NSDictionary z UIImage), następnie Disk Cache (system plików). W przypadku braku danych wykonywane jest żądanie sieciowe przez NSURLSession. Po załadowaniu dane są dekodowane, przechodzą przez transformacje i zapisywane w obu pamięciach podręcznych. Cały proces odbywa się w kolejce tła, wynik jest dostarczany do main queue.

• Memory Cache — sprawdzenie w O(1), przechowywanie UIImage z uwzględnieniem limitu pamięci
• Disk Cache — odczyt z systemu plików, przechowywanie skompresowanych danych
• NSURLSession — ładowanie z obsługą HTTP/2 i konfigurowalnym limitem czasu

Kategoria UIImageView

UIImageView+WebCache — kategoria Objective-C (dostępna z Swift), dodająca metodę sd_setImage. Ta metoda przyjmuje URL, placeholder, opcje (SDWebImageOptions) i completion-block. Kategoria automatycznie anuluje poprzednie żądanie przy ponownym użyciu komórki tabeli poprzez mechanizm sd_cancelCurrentImageLoad.

Główne klasy SDWebImage

Architektura SDWebImage jest podzielona na kilka modułów z jasno określonymi obszarami odpowiedzialności. Każda klasa rozwiązuje jedno zadanie — od ładowania do wyświetlania.

SDWebImageManager

SDWebImageManager — fasada dla wszystkich operacji na obrazach. Zawiera referencje do ImageCache (SDImageCache) i ImageLoader (SDWebImageDownloader). Poprzez delegata SDWebImageManagerDelegate można przechwycić ładowanie i zmienić URL lub zachowanie.

SDImageCache

SDImageCache — dwupoziomowa pamięć podręczna (memory + disk), inicjalizowana z unikalną przestrzenią nazw. Memory Cache przechowuje UIImage z konfigurowalnym limitem (domyślnie — do wyczerpania system memory warning). Disk Cache przechowuje dane w katalogu Library/Caches z konfigurowalnym okresem przechowywania (domyślnie 7 dni).

SDWebImageDownloader

SDWebImageDownloader — klient HTTP oparty na NSURLSession z obsługą nagłówków, limitów czasu i ponownych prób. Pobieracz łączy identyczne żądania w jedno wywołanie sieciowe (deduplikacja) i dystrybuuje wynik między wszystkich subskrybentów.

Architektura buforowania SDWebImage

SDWebImage implementuje dwupoziomowe buforowanie z deterministyczną kolejnością sprawdzania: najpierw pamięć, potem dysk. Kluczem pamięci podręcznej jest bezwzględny URL obrazu bez parametrów query lub MD5-hash z niego.

Po otrzymaniu memory warning iOS powiadamia SDImageCache przez UIApplicationDidReceiveMemoryWarningNotification, po czym Memory Cache jest całkowicie czyszczona. Disk Cache jest czyszczona według TTL lub po przekroczeniu limitu, z sortowaniem plików według daty ostatniego dostępu.

Do ręcznego zarządzania pamięcią podręczną dostępne są metody: clearMemory, clearDisk, calculateSize. Buforowanie można wyłączyć dla konkretnych żądań poprzez opcję SDWebImageCacheMemoryOnly lub SDWebImageAvoidAutoSetImage.

Przykłady użycia SDWebImage w Swift

SDWebImage udostępnia kilka interfejsów do ładowania obrazów: od prostej kategorii UIImageView po zaawansowany menedżer z niestandardowym przetwarzaniem.

Podstawowe ładowanie w UIImageView

sd_setImage — główna metoda do ładowania obrazu w UIImageView. Przyjmuje URL, placeholder i opcjonalne parametry przez Options i Context. Wszystkie Completion Handler są wykonywane w głównym wątku.

let imageView = UIImageView()
imageView.sd_setImage(
    with: URL(string: "https://example.com/photo.jpg"),
    placeholderImage: UIImage(named: "placeholder"),
    options: [.progressiveLoad, .retryFailed],
    context: [.imageThumbnailPixelSize : CGSize(width: 300, height: 300)]
)

Metoda zwraca SDWebImageToken (operację), którą można anulować w razie potrzeby. Wewnętrznie sd_setImage wywołuje SDWebImageManager.load, przekazując ImageView jako Target do automatycznego ustawienia obrazu.

Ładowanie z niestandardową transformacją

SDWebImage obsługuje Transformer — protokół z pojedynczą metodą transformedImage. Wbudowane transformacje: okrąg, zaokrąglenie, nałożenie filtra koloru, zmiana rozmiaru. Łączenie transformacji odbywa się za pomocą operatora &&.

let transformer = SDImageResizingTransformer(
    size: CGSize(width: 200, height: 200),
    scaleMode: .aspectFill
)
let roundedTransformer = SDImageRoundCornerTransformer(
    radius: 16,
    corners: .allCorners,
    borderWidth: 0
)
imageView.sd_setImage(
    with: url,
    placeholderImage: placeholder,
    context: [.imageTransformer : transformer && roundedTransformer]
)

Użycie z SwiftUI

Biblioteka udostępnia WebImage — komponent View dla SwiftUI z obsługą placeholder, wskaźnika postępu i obsługi błędów. Komponent automatycznie subskrybuje się do cyklu życia View i anuluje ładowanie przy zniknięciu.

struct CachedImageView: View {
    let url: URL

    var body: some View {
        WebImage(url: url) { phase in
            if let image = phase.image {
                image.resizable()
            } else if phase.error {
                Color.red
            } else {
                ProgressView()
            }
        }
    }
}

Image Transformations w SDWebImage

SDWebImage udostępnia elastyczny system transformacji obrazów poprzez protokół SDImageTransformer. Transformacje są stosowane po dekodowaniu, ale przed buforowaniem — wynik transformacji jest zapisywany na dysku pod nowym kluczem, eliminując ponowne zastosowanie przy kolejnych żądaniach.

Wbudowane transformacje obejmują: SDImageResizingTransformer (zmiana rozmiaru z trybem), SDImageRoundCornerTransformer (zaokrąglanie rogów z opcjonalną ramką), SDImageFlipTransformer (odbicie lustrzane) i SDImageFilterTransformer (filtry CoreImage). Łączenie odbywa się za pomocą operatora &&, tworząc łańcuch przetwarzania.

Do niestandardowych transformacji wystarczy zaimplementować protokół SDImageTransformer z metodą transformedImageWithImage:forKey:. Klucz transformacji jest automatycznie dodawany do klucza pamięci podręcznej, zapobiegając kolizjom między różnymi wersjami tego samego obrazu.

Porównanie SDWebImage z Kingfisher

Na platformie iOS głównymi konkurentami SDWebImage są Kingfisher (czysty Swift) i Nuke. Wybór między SDWebImage a Kingfisher często zależy od języka projektu i wymaganej funkcjonalności.

SDWebImage pozostaje preferowanym wyborem dla projektów w Objective-C lub projektów hybrydowych. Kingfisher lepiej nadaje się do projektów w czystym Swift dzięki bezpieczeństwu typów i natywnej składni Swift. Obie biblioteki mają podobną architekturę buforowania i szybkość.

Konfiguracja SDWebImage w projekcie iOS

Podłączenie SDWebImage odbywa się przez Swift Package Manager, CocoaPods lub Carthage. Biblioteka jest podzielona na moduły: główny (SDWebImage), Coder (dodatkowe formaty) i MapKit (dla MKAnnotationView).

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

// CocoaPods (Podfile)
pod 'SDWebImage', '~> 5.19.0'
// Wtyczki dla WebP i SVG:
pod 'SDWebImageWebPCoder'
pod 'SDWebImageSVGCoder'

Po instalacji biblioteka jest gotowa do użycia bez dodatkowej konfiguracji. Do dostosowania pamięci podręcznej tworzy się instancję SDImageCache z unikalną przestrzenią nazw, która jest przekazywana do SDWebImageManager podczas inicjalizacji. Globalna konfiguracja odbywa się przez SDWebImageManager.shared.

// Dostosowanie pamięci podręcznej
let config = SDImageCacheConfig()
config.maxDiskAge = 14 * 86400 // 14 dni zamiast 7
config.maxDiskSize = 500 * 1024 * 1024 // 500 MB
config.shouldCacheImagesInMemory = .true

let cache = SDImageCache(
    namespace: "custom",
    diskCacheDirectory: FileManager.default.urls(
        for: .cachesDirectory,
        in: .userDomainMask
    ).first?.appendingPathComponent("custom_cache"),
    config: config
)
SDWebImageManager.sharedImageCache = cache