Kingfisher — ما هو، المفاهيم الأساسية و ImageCache

ما هو Kingfisher؟

Kingfisher هي مكتبة للتحميل غير المتزامن والتخزين المؤقت للصور على منصات Apple، مكتوبة بالكامل بلغة Swift. مؤلف المكتبة هو Wei Wang (onevcat). توفر Kingfisher مجموعة من الأدوات لتحميل الصور من الشبكة مع التخزين المؤقت التلقائي والتحويلات ودعم تقنيات Swift الحديثة: async/await و Combine و Sendable.

تحتوي المكتبة على أكثر من 23,000 نجمة على GitHub وتُستخدم في تطبيقات مثل Telegram و Snapchat و Dropbox. تدعم Kingfisher GIF و APNG و HEIF وجميع تنسيقات الصور القياسية. يعيد كل طلب Result آمن النوع، مما يلغي أخطاء تحويل الأنواع.

تم بناء بنية Kingfisher على ثلاثة مكونات رئيسية: Manager (مدير التحميل)، Cache (ذاكرة تخزين مؤقت من مستويين) و Processor (التحويلات). هذه المكونات مرتبطة عبر بروتوكولات، مما يسمح باستبدال أي جزء دون تغيير التبعيات.

كيف يعمل Kingfisher: Manager و Cache

KingfisherManager هو الفئة المركزية التي تنسق تحميل الصور وتخزينها مؤقتاً ومعالجتها. يحتوي على مراجع لـ ImageCache و ImageDownloader ويوفر طريقة واحدة retrieveImage تعيد الصورة الجاهزة بعد المرور بجميع المراحل.

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

عند استدعاء retrieveImage، يتحقق Manager أولاً من ذاكرة التخزين المؤقت (Memory Cache) — NSCache مع UIImage، حيث يتم تشكيل المفتاح من URL المصدر و CacheSerializer. إذا تم العثور على الصورة، يتم إعادتها فوراً. في حالة عدم وجودها، يتم التحقق من التخزين المؤقت على القرص (Disk Cache) — القراءة من نظام الملفات مع فك التشفير عبر serializer. إذا كان التخزين المؤقت على القرص فارغاً، يتم تنفيذ طلب شبكة عبر ImageDownloader، ويتم فك تشفير النتيجة وتحويلها وحفظها في كلا مستويي التخزين المؤقت.

• Memory Cache — يعتمد على NSCache، يتم مسحه تلقائياً عند تلقي تحذير الذاكرة
• Disk Cache — تخزين ملفات مع TTL والتحقق من حد الحجم
• ImageDownloader — يعتمد على URLSession مع دعم تعديل الطلب عبر المعدِّلات

Swift Concurrency

بدءاً من الإصدار 7.0، يدعم Kingfisher بالكامل async/await. طريقة retrieveImage متاحة كدالة غير متزامنة، تعيد Result مباشرة دون كتل إكمال. هذا يسمح باستخدام المكتبة في بنى Swift الحديثة مع Structured Concurrency.

الوحدات الأساسية لـ Kingfisher

ينقسم Kingfisher إلى عدة وحدات، كل منها يحل مهمته الخاصة. هذا التقسيم يبسط الاختبار واستبدال المكونات.

KingfisherManager

KingfisherManager هو واجهة (Facade) تجمع بين التحميل والتخزين المؤقت والمعالجات. افتراضياً، يتم استخدام المفرد KingfisherManager.shared، ولكن يمكن إنشاء مثيل منفصل بإعدادات مخصصة لسيناريوهات معزولة (مثل اختبارات الوحدة).

ImageCache

ImageCache هو ذاكرة تخزين مؤقت من مستويين بإعدادات منفصلة للذاكرة والقرص. Memory Cache ليس له حد على عدد العناصر، لكن النظام يقوم بمسحه عند انخفاض الذاكرة. Disk Cache يخزن الملفات في دليل مع TTL قابل للتكوين (افتراضياً 7 أيام)، وحد للحجم (افتراضياً 0 — بدون حد) وتنظيف تلقائي.

ImageProcessor

ImageProcessor هو بروتوكول بطريقة واحدة process(item:options:) تعيد الصورة المعالجة. التطبيقات المضمنة: ResizingImageProcessor (تغيير الحجم)، RoundCornerImageProcessor (تدوير الزوايا)، BlurImageProcessor (تمويه غاوسي)، OverlayImageProcessor (تراكب الألوان). يمكن دمج المعالجات باستخدام العامل |>.

نظام التخزين المؤقت لـ Kingfisher

تعتمد بنية التخزين المؤقت لـ Kingfisher على مبدأ الكتابة من خلال (write-through): تُكتب البيانات إلى كلا المستويين في وقت واحد، ويبدأ القراءة من أسرع مستوى — الذاكرة. مفتاح التخزين المؤقت هو URL المطلق للصورة بعد إزالة معلمات الاستعلام.

لإدارة حجم Disk Cache، يتم حساب الحجم الإجمالي للملفات مع الترتيب حسب تاريخ آخر وصول. عند تجاوز الحد، تتم إزالة الملفات ذات تاريخ الوصول الأقدم حتى يصبح الحجم أقل من 50% من الحد. يحدث تنظيف TTL أثناء تهيئة التخزين المؤقت وعند كل استدعاء لـ cleanExpired.

أمثلة على استخدام Kingfisher في Swift

يوفر Kingfisher عدة واجهات لتحميل الصور: امتداد على UIImageView، ومدير منفصل، وView لـ SwiftUI.

التحميل في UIImageView عبر kf

kf هو خاصية namespace على UIImageView، توفر طرق setImage و cancelDownload ومؤشرات التحميل. تقبل طريقة setImage URLSource ومعاملات اختيارية Options و completionHandler.

import Kingfisher

imageView.kf.setImage(
    with: URL(string: "https://example.com/image.jpg"),
    placeholder: UIImage(named: "placeholder"),
    options: [
        .processor(RoundCornerImageProcessor(radius: .point(12))),
        .transition(.fade(0.3)),
        .cacheMemoryOnly
    ],
    progressBlock: { receivedSize, totalSize in
        print("تم التحميل \(receivedSize) / \(totalSize)")
    }
)

تعيد الطريقة DownloadTask الذي يدعم الإلغاء عبر cancel وتتبع التقدم. داخلياً، تستدعي setImage KingfisherManager.shared.retrieveImage مع كشف تلقائي لـ ImageView كـ Target.

الاستخدام مع async/await

بدءاً من Kingfisher 7.0، طريقة setImage متاحة في نسخة غير متزامنة. هذا يسمح بدمج تحميل الصور في Swift Structured Concurrency بدون استدعاءات إرجاع.

func loadAvatar() async {
    do {
        let result = try await imageView.kf.setImage(
            with: url,
            options: [.processor(ResizingImageProcessor(
                targetSize: CGSize(width: 100, height: 100)
            ))]
        )
        // result.image يحتوي على UIImage
    } catch {
        print("فشل: \(error)")
    }
}

KFImage لـ SwiftUI

KFImage هي View لـ SwiftUI، مشابهة لـ AsyncImage من iOS 15، ولكن مع دعم كامل للتخزين المؤقت لـ Kingfisher. تستخدم View تلقائياً KingfisherManager.shared ولكنها تدعم مديراً مخصصاً عبر المعدِّل .configure.

struct AvatarView: View {
    let url: URL

    var body: some View {
        KFImage(url)
            .placeholder { ProgressView() }
            .resizable()
            .fade(duration: 0.25)
            .forceTransition()
            .frame(width: 80, height: 80)
            .cornerRadius(40)
    }
}

مؤشرات التحميل في Kingfisher

يوفر Kingfisher نظام مؤشرات مدمج لعرض تقدم تحميل الصورة. IndicatorType هو تعداد بثلاث خيارات: .activity (UIActivityIndicatorView)، .progress (UIProgressView) و .custom (تطبيق مخصص لبروتوكول Indicator). يظهر المؤشر تلقائياً فوق ImageView أثناء التحميل ويختفي بعد الانتهاء.

لمؤشر مخصص، يجب تنفيذ بروتوكول Indicator بطريقتين startAnimatingView() و stopAnimatingView(). هذا يسمح بحلول هجينة: هيكل عظمي مع رسوم متحركة shimmer، وصورة placeholder مع ظهور تدريجي، أو شعار مع رسوم متحركة للشفافية. يدعم Kingfisher أيضاً تعيين المؤشر عالمياً عبر KingfisherManager.shared.defaultOptions.

Kingfisher مقابل SDWebImage

على منصة iOS، تعتبر Kingfisher و SDWebImage المكتبتين المهيمنتين لتحميل الصور. يعتمد الاختيار بينهما على لغة المشروع ومتطلبات الأداء والنظام البيئي.

الميزة الرئيسية لـ Kingfisher هي بنيتها القائمة على Swift أولاً: دعم كامل لـ async/await و Combine Publishers و Sendable وأنواع Result. تحتفظ SDWebImage بالريادة بفضل نظامها البيئي الأوسع من الإضافات (WebP, SVG, MapKit) ودعم Objective-C.

إعداد Kingfisher في مشروع iOS

يتم تثبيت Kingfisher عبر Swift Package Manager أو CocoaPods أو Carthage. بعد التثبيت، يكفي استيراد الوحدة واستدعاء أي طريقة تحميل — المكتبة جاهزة للاستخدام بدون إعداد إضافي.

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

// CocoaPods (Podfile)
pod 'Kingfisher', '~> 7.12'

لتخصيص الإعدادات العامة، يُستخدم KingfisherManager.shared. يمكن تغيير مهلة المحمل واستراتيجية التخزين المؤقت والمعالجات الافتراضية. أدناه مثال على تكوين ذاكرة تخزين مؤقت بسعة 500 ميغابايت مع TTL لمدة 14 يوماً.

let cache = ImageCache(name: "custom")
cache.memoryStorage.config.totalCostLimit = 100 * 1024 * 1024
cache.diskStorage.config.sizeLimit = 500 * 1024 * 1024
cache.diskStorage.config.expiration = .days(14)
KingfisherManager.shared.cache = cache

ImageDownloader يتم تكوينه أيضاً عبر المدير: يمكن تعيين URLSessionConfiguration مخصصة بمهلات ورؤوس وسياسات تخزين مؤقت. لمراقبة التقدم، تتوفر وحدة KFIndicator مع دعم لـ ActivityIndicator و ProgressView والمؤشرات المخصصة.