SDWebImage: apa itu, konsep kunci dan UIImageView

Apa itu SDWebImage?

SDWebImage — perpustakaan untuk pemuatan gambar asinkron di platform Apple (iOS, macOS, tvOS, watchOS). Ini menyediakan kategori untuk UIImageView dengan metode sd_setImage yang dalam satu baris memuat, menyimpan cache, dan menampilkan gambar dari sumber mana pun.

Perpustakaan ini mendukung pemuatan progresif (gambar ditampilkan saat byte diterima), gambar animasi (GIF, APNG), transformasi (pembulatan, pemotongan, penambahan watermark), dan decoder kustom. Menurut GitHub Stats, SDWebImage memiliki lebih dari 25 ribu bintang dan digunakan di aplikasi besar seperti Twitter, Pinterest, dan Instagram.

Arsitektur dibangun di atas rantai komponen: Coder (decoding), Cache (penyimpanan), Loader (jaringan), dan Transformer (pemrosesan). Setiap komponen dapat diganti, memungkinkan penyesuaian perpustakaan dengan kebutuhan spesifik proyek.

Bagaimana cara kerja SDWebImage: manajer dan cache

SDWebImageManager — komponen sentral yang mengoordinasikan proses pemuatan. Menerima URL, memeriksa cache, memuat data, mendekodenya menjadi UIImage, dan meneruskannya ke ImageView atau Completion Handler. Manajer bekerja melalui singleton shared, dapat diakses dari bagian mana pun dari aplikasi.

Proses pemuatan

Manajer secara berurutan memeriksa Memory Cache (NSDictionary dengan UIImage), kemudian Disk Cache (sistem file). Jika data tidak ditemukan, permintaan jaringan dilakukan melalui NSURLSession. Setelah dimuat, data didekode, melewati transformasi, dan disimpan di kedua cache. Seluruh proses berlangsung di antrian latar belakang, hasilnya dikirim ke main queue.

• Memory Cache — pemeriksaan dalam O(1), penyimpanan UIImage dengan mempertimbangkan batas memori
• Disk Cache — membaca dari sistem file, menyimpan data terkompresi
• NSURLSession — pemuatan dengan dukungan HTTP/2 dan batas waktu yang dapat dikonfigurasi

Kategori UIImageView

UIImageView+WebCache — kategori Objective-C (dapat diakses dari Swift) yang menambahkan metode sd_setImage. Metode ini menerima URL, placeholder, opsi (SDWebImageOptions), dan completion-block. Kategori secara otomatis membatalkan permintaan sebelumnya saat penggunaan ulang sel tabel melalui mekanisme sd_cancelCurrentImageLoad.

Kelas utama SDWebImage

Arsitektur SDWebImage dibagi menjadi beberapa modul dengan area tanggung jawab yang jelas. Setiap kelas menyelesaikan satu tugas — dari pemuatan hingga penampilan.

SDWebImageManager

SDWebImageManager — facade untuk semua operasi gambar. Berisi referensi ke ImageCache (SDImageCache) dan ImageLoader (SDWebImageDownloader). Melalui delegasi SDWebImageManagerDelegate, pemuatan dapat dicegat dan URL atau perilaku dapat diubah.

SDImageCache

SDImageCache — cache dua tingkat (memory + disk), diinisialisasi dengan namespace unik. Memory Cache menyimpan UIImage dengan batas yang dapat dikonfigurasi (default — hingga system memory warning). Disk Cache menyimpan data di direktori Library/Caches dengan masa penyimpanan yang dapat dikonfigurasi (default 7 hari).

SDWebImageDownloader

SDWebImageDownloader — klien HTTP berbasis NSURLSession dengan dukungan untuk header, batas waktu, dan percobaan ulang. Pengunduh menggabungkan permintaan identik menjadi satu panggilan jaringan (deduplikasi) dan mendistribusikan hasil ke semua pelanggan.

Arsitektur caching SDWebImage

SDWebImage mengimplementasikan caching dua tingkat dengan urutan pemeriksaan deterministik: pertama memori, kemudian disk. Kunci cache adalah URL absolut gambar tanpa parameter query atau hash MD5 darinya.

Saat menerima memory warning, iOS memberi tahu SDImageCache melalui UIApplicationDidReceiveMemoryWarningNotification, setelah itu Memory Cache dibersihkan sepenuhnya. Disk Cache dibersihkan berdasarkan TTL atau saat melebihi batas, dengan mengurutkan file berdasarkan tanggal akses terakhir.

Untuk manajemen cache manual, tersedia metode: clearMemory, clearDisk, calculateSize. Caching dapat dinonaktifkan untuk permintaan tertentu melalui opsi SDWebImageCacheMemoryOnly atau SDWebImageAvoidAutoSetImage.

Contoh penggunaan SDWebImage di Swift

SDWebImage menyediakan beberapa antarmuka untuk memuat gambar: dari kategori UIImageView sederhana hingga manajer tingkat lanjut dengan pemrosesan kustom.

Pemuatan dasar di UIImageView

sd_setImage — metode utama untuk memuat gambar di UIImageView. Menerima URL, placeholder, dan parameter opsional melalui Options dan Context. Semua Completion Handler dijalankan di thread utama.

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

Metode mengembalikan SDWebImageToken (operasi) yang dapat dibatalkan jika diperlukan. Di dalamnya, sd_setImage memanggil SDWebImageManager.load, meneruskan ImageView sebagai Target untuk pengaturan gambar otomatis.

Pemuatan dengan transformasi kustom

SDWebImage mendukung Transformer — protokol dengan metode tunggal transformedImage. Transformasi bawaan: lingkaran, pembulatan, penerapan filter warna, perubahan ukuran. Menggabungkan transformasi dilakukan dengan operator &&.

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

Penggunaan dengan SwiftUI

Perpustakaan menyediakan WebImage — komponen View untuk SwiftUI dengan dukungan placeholder, indikator kemajuan, dan penanganan kesalahan. Komponen secara otomatis berlangganan ke siklus hidup View dan membatalkan pemuatan saat menghilang.

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

SDWebImage menyediakan sistem transformasi gambar yang fleksibel melalui protokol SDImageTransformer. Transformasi diterapkan setelah decoding tetapi sebelum caching — hasil transformasi disimpan di disk di bawah kunci baru, mencegah penerapan ulang pada permintaan berikutnya.

Transformasi bawaan meliputi: SDImageResizingTransformer (perubahan ukuran dengan mode), SDImageRoundCornerTransformer (pembulatan sudut dengan batas opsional), SDImageFlipTransformer (pencerminan), dan SDImageFilterTransformer (filter CoreImage). Penggabungan dilakukan dengan operator &&, menciptakan rantai pemrosesan.

Untuk transformasi kustom, cukup implementasikan protokol SDImageTransformer dengan metode transformedImageWithImage:forKey:. Kunci transformasi secara otomatis ditambahkan ke kunci cache, mencegah tabrakan antara versi berbeda dari gambar yang sama.

Perbandingan SDWebImage dengan Kingfisher

Di platform iOS, pesaing utama SDWebImage adalah Kingfisher (Swift murni) dan Nuke. Pilihan antara SDWebImage dan Kingfisher sering tergantung pada bahasa proyek dan fungsionalitas yang diperlukan.

SDWebImage tetap menjadi pilihan utama untuk proyek Objective-C atau proyek hibrida. Kingfisher lebih cocok untuk proyek Swift murni berkat keamanan tipe dan sintaks Swift asli. Kedua perpustakaan memiliki arsitektur caching dan kecepatan yang serupa.

Pengaturan SDWebImage di proyek iOS

Penghubungan SDWebImage dilakukan melalui Swift Package Manager, CocoaPods, atau Carthage. Perpustakaan dibagi menjadi modul: utama (SDWebImage), Coder (format tambahan), dan MapKit (untuk 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'
// Plugin untuk WebP dan SVG:
pod 'SDWebImageWebPCoder'
pod 'SDWebImageSVGCoder'

Setelah instalasi, perpustakaan siap digunakan tanpa konfigurasi tambahan. Untuk penyesuaian cache, dibuat instance SDImageCache dengan namespace unik, yang diteruskan ke SDWebImageManager saat inisialisasi. Konfigurasi global dilakukan melalui SDWebImageManager.shared.

// Kustomisasi cache
let config = SDImageCacheConfig()
config.maxDiskAge = 14 * 86400 // 14 hari bukan 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