Kingfisher — یہ کیا ہے، بنیادی تصورات اور ImageCache

Kingfisher کیا ہے؟

Kingfisher Apple پلیٹ فارمز پر غیر متزامن تصویری لوڈنگ اور کیشنگ کے لیے ایک لائبریری ہے، جو مکمل طور پر Swift میں لکھی گئی ہے۔ لائبریری کے مصنف Wei Wang (onevcat) ہیں۔ Kingfisher خودکار کیشنگ، تبدیلیوں اور جدید Swift ٹیکنالوجیز (async/await، Combine، Sendable) کی معاونت کے ساتھ نیٹ ورک سے تصاویر لوڈ کرنے کے لیے ٹولز کا ایک سیٹ فراہم کرتا ہے۔

لائبریری کے GitHub پر 23,000 سے زیادہ ستارے ہیں اور یہ Telegram، Snapchat اور Dropbox جیسی ایپلیکیشنز میں استعمال ہوتی ہے۔ Kingfisher GIF، APNG، HEIF اور تمام معیاری تصویری فارمیٹس کو سپورٹ کرتا ہے۔ ہر درخواست ایک ٹائپ سیف Result لوٹاتی ہے، جو ٹائپ کاسٹنگ کی غلطیوں کو ختم کرتا ہے۔

Kingfisher کا فن تعمیر تین اہم اجزاء پر بنایا گیا ہے: Manager (ڈاؤن لوڈ مینیجر)، Cache (دو سطحی کیش) اور Processor (تبدیلیاں)۔ یہ اجزاء پروٹوکول کے ذریعے جڑے ہوئے ہیں، جس سے انحصار تبدیل کیے بغیر کسی بھی حصے کو تبدیل کیا جا سکتا ہے۔

Kingfisher کیسے کام کرتا ہے: Manager اور Cache

KingfisherManager مرکزی کلاس ہے جو تصویری لوڈنگ، کیشنگ اور پروسیسنگ کو مربوط کرتی ہے۔ اس میں ImageCache اور ImageDownloader کے حوالہ جات ہوتے ہیں اور یہ ایک واحد طریقہ retrieveImage فراہم کرتا ہے جو تمام مراحل سے گزرنے کے بعد تیار تصویر لوٹاتا ہے۔

لوڈنگ کا عمل

retrieveImage کو کال کرنے پر، Manager پہلے Memory Cache کو چیک کرتا ہے — UIImage کے ساتھ ایک NSCache، جہاں کلید ماخذ URL اور CacheSerializer سے بنتی ہے۔ اگر تصویر مل جاتی ہے، تو اسے فوری طور پر لوٹا دیا جاتا ہے۔ نہ ملنے پر، Disk Cache کو چیک کیا جاتا ہے — serializer کے ذریعے ڈیکرپشن کے ساتھ فائل سسٹم سے پڑھنا۔ اگر ڈسک کیش خالی ہے، تو ImageDownloader کے ذریعے نیٹ ورک کی درخواست کی جاتی ہے، نتیجہ ڈی کوڈ، تبدیل اور دونوں کیش سطحوں میں محفوظ کیا جاتا ہے۔

• Memory Cache — NSCache پر مبنی، میموری وارننگ پر خود بخود صاف ہو جاتا ہے
• Disk Cache — TTL اور سائز کی حد کی جانچ کے ساتھ فائل ذخیرہ
• ImageDownloader — ترمیم کنندگان کے ذریعے درخواست میں ترمیم کی معاونت کے ساتھ URLSession پر مبنی

Swift Concurrency

ورژن 7.0 سے، Kingfisher async/await کو مکمل طور پر سپورٹ کرتا ہے۔ retrieveImage طریقہ ایک غیر متزامن فنکشن کے طور پر دستیاب ہے، جو تکمیلی بلاکس کے بغیر براہ راست Result لوٹاتا ہے۔ یہ Structured Concurrency کے ساتھ جدید Swift فن تعمیر میں لائبریری کے استعمال کی اجازت دیتا ہے۔

Kingfisher کے بنیادی ماڈیولز

Kingfisher کئی ماڈیولز میں تقسیم ہے، ہر ایک اپنے کام کو حل کرتا ہے۔ یہ تقسیم جانچ اور اجزاء کی تبدیلی کو آسان بناتی ہے۔

KingfisherManager

KingfisherManager ایک سہولت کار ہے جو لوڈنگ، کیش اور پروسیسرز کو یکجا کرتا ہے۔ ڈیفالٹ طور پر، سنگلٹن 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 کی ہر کال پر ہوتی ہے۔

Swift میں Kingfisher استعمال کرنے کی مثالیں

Kingfisher تصاویر لوڈ کرنے کے لیے کئی انٹرفیس فراہم کرتا ہے: UIImageView پر ایک توسیع، ایک علیحدہ مینیجر اور ایک SwiftUI View۔

kf کے ذریعے UIImageView میں لوڈ کرنا

kf UIImageView پر ایک Namespace خصوصیت ہے، جو 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 ImageView کو Target کے طور پر خودکار پتہ لگانے کے ساتھ KingfisherManager.shared.retrieveImage کو کال کرتا ہے۔

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

SwiftUI کے لیے KFImage

KFImage ایک SwiftUI View ہے، جو iOS 15 کے AsyncImage سے ملتا جلتا ہے، لیکن مکمل 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() طریقوں کے ساتھ نافذ کرنا ضروری ہے۔ یہ ہائبرڈ حل کی اجازت دیتا ہے: چمکتی اینیمیشن کے ساتھ کنکال، بتدریج ظاہر ہونے والی پلیس ہولڈر تصویر یا شفافیت کی اینیمیشن کے ساتھ لوگو۔ Kingfisher KingfisherManager.shared.defaultOptions کے ذریعے عالمی سطح پر اشارہ سیٹ کرنے کی بھی حمایت کرتا ہے۔

Kingfisher بمقابلہ SDWebImage

iOS پلیٹ فارم پر، Kingfisher اور SDWebImage تصویری لوڈنگ کی دو غالب لائبریریاں ہیں۔ ان کے درمیان انتخاب پروجیکٹ کی زبان، کارکردگی کی ضروریات اور ماحولیاتی نظام پر منحصر ہے۔

Kingfisher کا بنیادی فائدہ اس کا Swift-first فن تعمیر ہے: async/await، Combine Publishers، Sendable اور Result اقسام کے لیے مکمل حمایت۔ SDWebImage وسیع پلگ ان ماحولیاتی نظام (WebP, SVG, MapKit) اور Objective-C حمایت کی وجہ سے اپنی قیادت برقرار رکھے ہوئے ہے۔

iOS پروجیکٹ میں Kingfisher ترتیب دینا

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 استعمال کریں۔ آپ ڈاؤن لوڈر کا ٹائم آؤٹ، کیش حکمت عملی اور ڈیفالٹ پروسیسرز تبدیل کر سکتے ہیں۔ ذیل میں 14 دن کے TTL کے ساتھ 500 MB کیش ترتیب دینے کی مثال دی گئی ہے۔

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 اور کسٹم اشارے کی حمایت کے ساتھ دستیاب ہے۔