SDWebImage: ما هو، المفاهيم الأساسية و UIImageView

ما هو SDWebImage؟

SDWebImage هي مكتبة للتحميل غير المتزامن للصور على منصات Apple (iOS، macOS، tvOS، watchOS). توفر فئة UIImageView مع طريقة sd_setImage التي تقوم بتحميل الصورة وتخزينها مؤقتًا وعرضها من أي مصدر في سطر واحد من الكود.

تدعم المكتبة التحميل التدريجي (تظهر الصورة أثناء استلام البايتات)، والصور المتحركة (GIF، APNG)، والتحويلات (التدوير، القص، إضافة علامة مائية)، وأجهزة فك التشفير المخصصة. وفقًا لـ إحصائيات GitHub، يحتوي SDWebImage على أكثر من 25,000 نجمة ويُستخدم في تطبيقات رئيسية بما في ذلك Twitter و Pinterest و Instagram.

الهندسة المعمارية مبنية على سلسلة من المكونات: Coder (فك التشفير)، Cache (التخزين)، Loader (الشبكة) و Transformer (المعالجة). كل مكون قابل للاستبدال، مما يسمح بتكييف المكتبة مع متطلبات المشروع المحددة.

كيف يعمل SDWebImage: المدير والذاكرة المؤقتة

SDWebImageManager هو المكون المركزي الذي ينسق عملية التحميل. يقبل عنوان URL، ويتحقق من الذاكرة المؤقتة، ويحمل البيانات، ويفك تشفيرها إلى UIImage، ويمررها إلى ImageView أو Completion Handler. يعمل المدير من خلال singleton مشترك، يمكن الوصول إليه من أي مكان في التطبيق.

عملية التحميل

يتحقق المدير بالتسلسل من ذاكرة التخزين المؤقت (NSDictionary مع UIImage)، ثم ذاكرة التخزين المؤقت على القرص (نظام الملفات). في حالة عدم وجودها، يتم إجراء طلب شبكة عبر NSURLSession. بعد التحميل، يتم فك تشفير البيانات، وتمريرها عبر التحويلات، وحفظها في كلا ذاكرتي التخزين المؤقت. تتم العملية بأكملها في قائمة انتظار خلفية، ويتم تسليم النتائج إلى قائمة الانتظار الرئيسية.

• ذاكرة التخزين المؤقت — بحث O(1)، تخزين UIImage بحد ذاكرة قابل للتكوين
• ذاكرة التخزين المؤقت على القرص — قراءة من نظام الملفات، تخزين بيانات مضغوطة
• NSURLSession — تحميل مع دعم HTTP/2 ومهلة زمنية قابلة للتكوين

فئة UIImageView

UIImageView+WebCache هي فئة Objective-C (يمكن الوصول إليها من Swift) تضيف طريقة sd_setImage. تقبل هذه الطريقة عنوان URL، وصورة placeholder، وخيارات (SDWebImageOptions)، وكتلة إتمام. تلغي الفئة تلقائيًا الطلب السابق عند إعادة استخدام خلية الجدول من خلال آلية sd_cancelCurrentImageLoad.

الفئات الرئيسية لـ SDWebImage

تنقسم بنية SDWebImage إلى عدة وحدات ذات مناطق مسؤولية واضحة. كل فئة تحل مهمة واحدة — من التحميل إلى العرض.

SDWebImageManager

SDWebImageManager هو الواجهة لجميع عمليات الصور. يحتوي على مراجع لـ ImageCache (SDImageCache) و ImageLoader (SDWebImageDownloader). من خلال المفوض SDWebImageManagerDelegate، يمكن اعتراض التحميل وتغيير URL أو السلوك.

SDImageCache

SDImageCache هو ذاكرة تخزين مؤقت من مستويين (ذاكرة + قرص) يتم تهيئتها بنطاق فريد. يخزن Memory Cache UIImage بحد قابل للتكوين (افتراضيًا — حتى تحذير ذاكرة النظام). يخزن Disk Cache البيانات في دليل Library/Caches بمدة تخزين قابلة للتكوين (افتراضيًا 7 أيام).

SDWebImageDownloader

SDWebImageDownloader هو عميل HTTP يعتمد على NSURLSession مع دعم الرؤوس والمهلات وإعادة المحاولة. يقوم المُنزّل بإزالة تكرار الطلبات المتطابقة في استدعاء شبكة واحد وتوزيع النتيجة على جميع المشتركين.

هندسة التخزين المؤقت لـ SDWebImage

يطبق SDWebImage تخزينًا مؤقتًا من مستويين بترتيب تحقق حتمي: أولاً الذاكرة، ثم القرص. مفتاح التخزين المؤقت هو عنوان URL المطلق للصورة بدون معلمات الاستعلام أو تجزئة MD5 الخاصة به.

عند استلام تحذير ذاكرة، يخطر iOS SDImageCache من خلال UIApplicationDidReceiveMemoryWarningNotification، وبعد ذلك يتم مسح Memory Cache بالكامل. يتم مسح Disk Cache حسب TTL أو عند تجاوز الحد، مع ترتيب الملفات حسب تاريخ آخر وصول.

لإدارة ذاكرة التخزين المؤقت يدويًا، تتوفر الطرق التالية: clearMemory، clearDisk، calculateSize. يمكن تعطيل التخزين المؤقت لطلبات محددة باستخدام خيارات SDWebImageCacheMemoryOnly أو SDWebImageAvoidAutoSetImage.

أمثلة استخدام SDWebImage في Swift

توفر SDWebImage عدة واجهات لتحميل الصور: من فئة UIImageView البسيطة إلى المدير المتقدم مع المعالجة المخصصة.

التحميل الأساسي في UIImageView

sd_setImage هي الطريقة الأساسية لتحميل صورة في UIImageView. تقبل عنوان URL، وصورة placeholder، ومعلمات اختيارية من خلال Options و Context. يتم تنفيذ جميع Completion Handler في السلسلة الرئيسية.

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()
            }
        }
    }
}

تحويلات الصور في SDWebImage

يوفر SDWebImage نظام تحويل مرن من خلال بروتوكول SDImageTransformer. تُطبق التحويلات بعد فك التشفير ولكن قبل التخزين المؤقت — يتم تخزين نتيجة التحويل على القرص تحت مفتاح جديد، مما يمنع إعادة التطبيق في الطلبات اللاحقة.

تشمل التحويلات المضمنة: SDImageResizingTransformer (تغيير الحجم مع mode)، 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.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 بنطاق فريد، ومرره إلى SDWebImageManager أثناء التهيئة. يتم التكوين العام من خلال SDWebImageManager.shared.

// تخصيص التخزين المؤقت
let config = SDImageCacheConfig()
config.maxDiskAge = 14 * 86400 // 14 يومًا بدلاً من 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