SDWebImage: این چیست، مفاهیم کلیدی و UIImageView

SDWebImage چیست؟

SDWebImage — کتابخانه بارگذاری ناهمگام تصاویر در پلتفرم‌های Apple (iOS, macOS, tvOS, watchOS). این کتابخانه یک رده برای UIImageView با متد sd_setImage فراهم می‌کند که در یک خط تصویر را از هر منبعی بارگذاری، کش و نمایش می‌دهد.

این کتابخانه از بارگذاری تدریجی (نمایش تصویر با دریافت بایت‌ها)، تصاویر متحرک (GIF, APNG)، تبدیل‌ها (گرد کردن، برش، افزودن واترمارک) و رمزگشاهای سفارشی پشتیبانی می‌کند. طبق GitHub Stats، SDWebImage بیش از ۲۵ هزار ستاره دارد و در برنامه‌های بزرگی از جمله Twitter، Pinterest و Instagram استفاده می‌شود.

معماری بر زنجیره‌ای از کامپوننت‌ها ساخته شده است: Coder (رمزگشایی)، Cache (ذخیره‌سازی)، Loader (شبکه) و Transformer (پردازش). هر کامپوننت قابل تعویض است که امکان تطبیق کتابخانه با نیازهای خاص پروژه را فراهم می‌کند.

SDWebImage چگونه کار می‌کند: مدیر و کش

SDWebImageManager — کامپوننت مرکزی که فرآیند بارگذاری را هماهنگ می‌کند. URL را دریافت می‌کند، کش را بررسی می‌کند، داده‌ها را بارگذاری می‌کند، آنها را به UIImage رمزگشایی می‌کند و به ImageView یا Completion Handler تحویل می‌دهد. مدیر از طریق singleton shared کار می‌کند و از هر نقطه برنامه قابل دسترسی است.

فرآیند بارگذاری

مدیر به ترتیب Memory Cache (NSDictionary با UIImage) و سپس Disk Cache (سیستم فایل) را بررسی می‌کند. در صورت عدم وجود داده، درخواست شبکه از طریق NSURLSession انجام می‌شود. پس از بارگذاری، داده‌ها رمزگشایی می‌شوند، از تبدیل‌ها عبور می‌کنند و در هر دو کش ذخیره می‌شوند. کل فرآیند در صف پس‌زمینه اجرا می‌شود و نتیجه در main queue تحویل داده می‌شود.

• Memory Cache — بررسی در O(1)، ذخیره UIImage با در نظر گرفتن محدودیت حافظه
• Disk Cache — خواندن از سیستم فایل، ذخیره داده‌های فشرده
• NSURLSession — بارگذاری با پشتیبانی HTTP/2 و مهلت زمانی قابل تنظیم

رده UIImageView

UIImageView+WebCache — رده Objective-C (قابل دسترسی از Swift) که متد sd_setImage را اضافه می‌کند. این متد URL، placeholder، گزینه‌ها (SDWebImageOptions) و completion-block را دریافت می‌کند. رده به طور خودکار درخواست قبلی را هنگام استفاده مجدد از سلول جدول از طریق مکانیزم sd_cancelCurrentImageLoad لغو می‌کند.

کلاس‌های اصلی SDWebImage

معماری SDWebImage به چندین ماژول با مناطق مسئولیت مشخص تقسیم شده است. هر کلاس یک وظیفه را حل می‌کند — از بارگذاری تا نمایش.

SDWebImageManager

SDWebImageManager — facade برای تمام عملیات روی تصاویر. شامل ارجاعات به ImageCache (SDImageCache) و ImageLoader (SDWebImageDownloader) است. از طریق delegate SDWebImageManagerDelegate می‌توان بارگذاری را رهگیری و URL یا رفتار را تغییر داد.

SDImageCache

SDImageCache — کش دو سطحی (memory + disk) که با namespace منحصر‌به‌فرد مقداردهی می‌شود. Memory Cache UIImage را با محدودیت قابل تنظیم ذخیره می‌کند (پیش‌فرض — تا system memory warning). Disk Cache داده‌ها را در دایرکتوری Library/Caches با مدت ذخیره‌سازی قابل تنظیم ذخیره می‌کند (پیش‌فرض ۷ روز).

SDWebImageDownloader

SDWebImageDownloader — کلاینت HTTP مبتنی بر NSURLSession با پشتیبانی از هدرها، مهلت زمانی و تلاش مجدد. بارگذار درخواست‌های یکسان را در یک فراخوانی شبکه ترکیب می‌کند (deduplication) و نتیجه را بین همه مشترکین توزیع می‌کند.

معماری کش SDWebImage

SDWebImage کش‌کردن دو سطحی با ترتیب بررسی قطعی پیاده‌سازی می‌کند: ابتدا حافظه، سپس دیسک. کلید کش URL مطلق تصویر بدون پارامترهای query یا MD5-hash آن است.

پس از دریافت memory warning، iOS از طریق UIApplicationDidReceiveMemoryWarningNotification به SDImageCache اخطار می‌دهد و پس از آن Memory Cache کاملاً پاک می‌شود. Disk Cache بر اساس TTL یا پس از تجاوز از حد مجاز با مرتب‌سازی فایل‌ها بر اساس تاریخ آخرین دسترسی پاک می‌شود.

برای مدیریت دستی کش، متدهای زیر در دسترس هستند: clearMemory، clearDisk، calculateSize. کش‌کردن را می‌توان برای درخواست‌های خاص از طریق گزینه SDWebImageCacheMemoryOnly یا SDWebImageAvoidAutoSetImage غیرفعال کرد.

نمونه‌های استفاده از SDWebImage در Swift

SDWebImage چندین رابط برای بارگذاری تصاویر ارائه می‌دهد: از رده ساده UIImageView تا مدیر پیشرفته با پردازش سفارشی.

بارگذاری پایه در UIImageView

sd_setImage — روش اصلی برای بارگذاری تصویر در UIImageView. URL، placeholder و پارامترهای اختیاری را از طریق Options و Context دریافت می‌کند. تمام Completion Handlerها در thread اصلی اجرا می‌شوند.

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

متد SDWebImageToken (عملیات) را برمی‌گرداند که در صورت نیاز می‌توان آن را لغو کرد. در داخل، sd_setImage SDWebImageManager.load را فراخوانی می‌کند و ImageView را به عنوان Target برای تنظیم خودکار تصویر ارسال می‌کند.

بارگذاری با تبدیل سفارشی

SDWebImage از Transformer — پروتکلی با یک متد transformedImage پشتیبانی می‌کند. تبدیل‌های داخلی: دایره، گرد کردن، اعمال فیلتر رنگی، تغییر اندازه. ترکیب تبدیل‌ها با عملگر && انجام می‌شود.

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

استفاده با SwiftUI

کتابخانه WebImage — کامپوننت View برای SwiftUI با پشتیبانی از placeholder، نشانگر پیشرفت و مدیریت خطا ارائه می‌دهد. کامپوننت به طور خودکار در چرخه حیات View مشترک می‌شود و بارگذاری را هنگام ناپدید شدن لغو می‌کند.

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 در SDWebImage

SDWebImage یک سیستم تبدیل تصویر انعطاف‌پذیر از طریق پروتکل SDImageTransformer ارائه می‌دهد. تبدیل‌ها پس از رمزگشایی اما قبل از کش‌کردن اعمال می‌شوند — نتیجه تبدیل تحت کلید جدیدی روی دیسک ذخیره می‌شود و از اعمال مجدد در درخواست‌های بعدی جلوگیری می‌کند.

تبدیل‌های داخلی شامل: SDImageResizingTransformer (تغییر اندازه با حالت)، SDImageRoundCornerTransformer (گرد کردن گوشه‌ها با حاشیه اختیاری)، SDImageFlipTransformer (بازتاب آینه‌ای) و SDImageFilterTransformer (فیلترهای CoreImage). ترکیب با عملگر && یک زنجیره پردازش ایجاد می‌کند.

برای تبدیل‌های سفارشی کافی است پروتکل SDImageTransformer را با متد transformedImageWithImage:forKey: پیاده‌سازی کنید. کلید تبدیل به طور خودکار به کلید کش اضافه می‌شود و از برخورد بین نسخه‌های مختلف یک تصویر جلوگیری می‌کند.

مقایسه SDWebImage با Kingfisher

در پلتفرم iOS رقبای اصلی SDWebImage Kingfisher (Swift خالص) و Nuke هستند. انتخاب بین SDWebImage و Kingfisher اغلب به زبان پروژه و عملکرد مورد نیاز بستگی دارد.

SDWebImage انتخاب ارجح برای پروژه‌های Objective-C یا پروژه‌های هیبریدی باقی می‌ماند. Kingfisher به دلیل امنیت نوع و نحو بومی Swift برای پروژه‌های Swift خالص مناسب‌تر است. هر دو کتابخانه معماری کش و سرعت مشابهی دارند.

تنظیم SDWebImage در پروژه iOS

اتصال SDWebImage از طریق Swift Package Manager، CocoaPods یا Carthage انجام می‌شود. کتابخانه به ماژول‌ها تقسیم می‌شود: اصلی (SDWebImage)، Coder (فرمت‌های اضافی) و MapKit (برای 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'
// پلاگین‌های WebP و SVG:
pod 'SDWebImageWebPCoder'
pod 'SDWebImageSVGCoder'

پس از نصب، کتابخانه بدون پیکربندی اضافی آماده استفاده است. برای سفارشی‌سازی کش، نمونه‌ای از SDImageCache با namespace منحصربه‌فرد ایجاد می‌شود که در زمان مقداردهی به SDWebImageManager ارسال می‌شود. پیکربندی جهانی از طریق SDWebImageManager.shared انجام می‌شود.

// سفارشی‌سازی کش
let config = SDImageCacheConfig()
config.maxDiskAge = 14 * 86400 // ۱۴ روز به جای ۷
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