SDWebImage: co to je, klíčové pojmy a UIImageView

Co je SDWebImage?

SDWebImage — knihovna pro asynchronní načítání obrázků na platformách Apple (iOS, macOS, tvOS, watchOS). Poskytuje kategorii pro UIImageView s metodou sd_setImage, která na jeden řádek načte, uloží do mezipaměti a zobrazí obrázek z libovolného zdroje.

Knihovna podporuje progresivní načítání (obrázek se zobrazuje během přijímání bajtů), animované obrázky (GIF, APNG), transformace (zaoblení, oříznutí, přidání vodoznaku) a vlastní dekodéry. Podle GitHub Stats má SDWebImage více než 25 tisíc hvězd a je používán ve velkých aplikacích včetně Twitter, Pinterest a Instagram.

Architektura je postavena na řetězci komponent: Coder (dekódování), Cache (ukládání), Loader (síť) a Transformer (zpracování). Každá komponenta je nahraditelná, což umožňuje přizpůsobit knihovnu specifickým požadavkům projektu.

Jak funguje SDWebImage: správce a mezipaměť

SDWebImageManager — centrální komponenta koordinující proces načítání. Přijímá URL, kontroluje mezipaměť, načítá data, dekóduje je do UIImage a předává je do ImageView nebo Completion Handleru. Správce pracuje prostřednictvím shared singletonu, přístupného z libovolné části aplikace.

Proces načítání

Správce postupně kontroluje Memory Cache (NSDictionary s UIImage), poté Disk Cache (souborový systém). Při nenalezení dat se provádí síťový požadavek prostřednictvím NSURLSession. Po načtení jsou data dekódována, procházejí transformacemi a ukládají se do obou mezipamětí. Celý proces probíhá na pozadí, výsledek je doručen do main queue.

• Memory Cache — kontrola v O(1), ukládání UIImage s ohledem na limit paměti
• Disk Cache — čtení ze souborového systému, ukládání komprimovaných dat
• NSURLSession — načítání s podporou HTTP/2 a konfigurovatelným timeoutem

Kategorie UIImageView

UIImageView+WebCache — kategorie Objective-C (přístupná ze Swiftu), která přidává metodu sd_setImage. Tato metoda přijímá URL, placeholder, volby (SDWebImageOptions) a completion-blok. Kategorie automaticky ruší předchozí požadavek při opětovném použití buňky tabulky prostřednictvím mechanismu sd_cancelCurrentImageLoad.

Hlavní třídy SDWebImage

Architektura SDWebImage je rozdělena do několika modulů s jasnými oblastmi odpovědnosti. Každá třída řeší jeden úkol — od načítání po zobrazení.

SDWebImageManager

SDWebImageManager — fasáda pro všechny operace s obrázky. Obsahuje reference na ImageCache (SDImageCache) a ImageLoader (SDWebImageDownloader). Prostřednictvím delegáta SDWebImageManagerDelegate lze zachytit načítání a změnit URL nebo chování.

SDImageCache

SDImageCache — dvouúrovňová mezipaměť (memory + disk), inicializovaná s unikátním namespace. Memory Cache ukládá UIImage s konfigurovatelným limitem (výchozí — do system memory warning). Disk Cache ukládá data v adresáři Library/Caches s konfigurovatelnou dobou uložení (výchozí 7 dní).

SDWebImageDownloader

SDWebImageDownloader — HTTP klient založený na NSURLSession s podporou hlaviček, timeoutu a opakovaných pokusů. Stahovač spojuje identické požadavky do jednoho síťového volání (deduplikace) a distribuuje výsledek mezi všechny odběratele.

Architektura ukládání do mezipaměti SDWebImage

SDWebImage implementuje dvouúrovňové ukládání do mezipaměti s deterministickým pořadím kontroly: nejprve paměť, poté disk. Klíčem mezipaměti je absolutní URL obrázku bez query parametrů nebo MD5 hash z něj.

Při obdržení memory warningu iOS upozorní SDImageCache prostřednictvím UIApplicationDidReceiveMemoryWarningNotification, poté je Memory Cache zcela vyčištěna. Disk Cache je čištěna podle TTL nebo při překročení limitu, s řazením souborů podle data posledního přístupu.

Pro ruční správu mezipaměti jsou k dispozici metody: clearMemory, clearDisk, calculateSize. Ukládání do mezipaměti lze deaktivovat pro konkrétní požadavky prostřednictvím volby SDWebImageCacheMemoryOnly nebo SDWebImageAvoidAutoSetImage.

Příklady použití SDWebImage ve Swiftu

SDWebImage poskytuje několik rozhraní pro načítání obrázků: od jednoduché UIImageView kategorie po pokročilého správce s vlastním zpracováním.

Základní načítání v UIImageView

sd_setImage — hlavní metoda pro načítání obrázku v UIImageView. Přijímá URL, placeholder a volitelné parametry prostřednictvím Options a Context. Všechny Completion Handlery jsou prováděny v hlavním vlákně.

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 vrací SDWebImageToken (operaci), kterou lze v případě potřeby zrušit. Interně sd_setImage volá SDWebImageManager.load a předává ImageView jako Target pro automatické nastavení obrázku.

Načítání s vlastní transformací

SDWebImage podporuje Transformer — protokol s jedinou metodou transformedImage. Vestavěné transformace: kruh, zaoblení, aplikace barevného filtru, změna velikosti. Kombinování transformací se provádí pomocí operátoru &&.

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]
)

Použití se SwiftUI

Knihovna poskytuje WebImage — View komponentu pro SwiftUI s podporou placeholderu, indikátoru průběhu a zpracování chyb. Komponenta se automaticky přihlašuje k životnímu cyklu View a ruší načítání při zmizení.

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 v SDWebImage

SDWebImage poskytuje flexibilní systém transformací obrázků prostřednictvím protokolu SDImageTransformer. Transformace jsou aplikovány po dekódování, ale před uložením do mezipaměti — výsledek transformace je uložen na disku pod novým klíčem, čímž se eliminuje opakované použití při následujících požadavcích.

Vestavěné transformace zahrnují: SDImageResizingTransformer (změna velikosti s režimem), SDImageRoundCornerTransformer (zaoblení rohů s volitelným okrajem), SDImageFlipTransformer (zrcadlové odražení) a SDImageFilterTransformer (filtry CoreImage). Kombinování se provádí pomocí operátoru &&, čímž vzniká řetězec zpracování.

Pro vlastní transformace stačí implementovat protokol SDImageTransformer s metodou transformedImageWithImage:forKey:. Klíč transformace je automaticky přidán ke klíči mezipaměti, čímž se zabraňuje kolizím mezi různými verzemi stejného obrázku.

Srovnání SDWebImage s Kingfisher

Na platformě iOS jsou hlavními konkurenty SDWebImage Kingfisher (čistý Swift) a Nuke. Volba mezi SDWebImage a Kingfisher často závisí na jazyku projektu a požadované funkcionalitě.

SDWebImage zůstává preferovanou volbou pro projekty v Objective-C nebo hybridní projekty. Kingfisher je vhodnější pro projekty v čistém Swiftu díky typové bezpečnosti a nativní syntaxi Swift. Obě knihovny mají podobnou architekturu mezipaměti a rychlost.

Nastavení SDWebImage v iOS projektu

Připojení SDWebImage se provádí prostřednictvím Swift Package Manager, CocoaPods nebo Carthage. Knihovna je rozdělena do modulů: hlavní (SDWebImage), Coder (další formáty) a MapKit (pro 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'
// Pluginy pro WebP a SVG:
pod 'SDWebImageWebPCoder'
pod 'SDWebImageSVGCoder'

Po instalaci je knihovna připravena k použití bez další konfigurace. Pro přizpůsobení mezipaměti se vytvoří instance SDImageCache s unikátním namespace, která je předána SDWebImageManageru při inicializaci. Globální konfigurace se provádí prostřednictvím SDWebImageManager.shared.

// Přizpůsobení mezipaměti
let config = SDImageCacheConfig()
config.maxDiskAge = 14 * 86400 // 14 dní místo 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