Kingfisher لـ Swift: دليل شامل مع أمثلة

مقدمة عن Kingfisher: ما هو ولماذا تحتاجه

\n\n

Kingfisher هي مكتبة قوية وشائعة لـ Swift، مصممة لتحميل وتخزين الصور من الشبكة مؤقتًا. توفر للمطورين واجهة برمجة تطبيقات بسيطة ولكنها مرنة للعمل مع الصور في تطبيقات iOS و macOS و tvOS و watchOS. المكتبة مكتوبة بلغة Swift النقية ويتم دعمها بنشاط من قبل المجتمع.

\n\n

لماذا تحتاج Kingfisher؟ في تطبيقات الهواتف المحمولة الحديثة، يعد العمل مع الصور أحد المهام الرئيسية. يتوقع المستخدمون تحميلًا سريعًا للمحتوى، وتمريرًا سلسًا، واستهلاكًا ضئيلًا للبيانات. يحل Kingfisher هذه المشكلات من خلال إدارة تحميل الصور وتخزينها مؤقتًا (في الذاكرة وعلى القرص) وعرضها تلقائيًا. بدلاً من كتابة كود معقد لإدارة طلبات الشبكة ومعالجة الأخطاء والتخزين المؤقت، يمكنك ببساطة استدعاء طريقة واحدة setImage(with:).

\n\n

الإمكانيات الرئيسية:

\n

\n
• التحميل غير المتزامن: يتم تحميل الصور في خيط خلفي، دون حظر واجهة المستخدم.
\n
• التخزين المؤقت متعدد المستويات: يتم التحقق أولاً من ذاكرة التخزين المؤقت (وصول سريع)، ثم التخزين المؤقت على القرص (تخزين دائم).
\n
• معالجة الأخطاء: آليات مدمجة لمعالجة أخطاء الشبكة وعناوين URL غير الصالحة والبيانات التالفة.
\n
• دعم GIF و SVG: إمكانية عرض الصور المتحركة والرسومات المتجهة.
\n
• تحويلات الصور: طرق مدمجة لتغيير الحجم والقص وتطبيق المرشحات وتدوير الزوايا.
\n
• التكامل مع UIKit و AppKit: امتدادات لـ UIImageView و NSImageView و UIButton وعناصر أخرى.
\n
• إلغاء التحميل: إلغاء تلقائي للطلبات عند إعادة استخدام الخلايا في UITableView/UICollectionView.
\n

\n\n

Kingfisher ليس مجرد أداة تحميل صور، بل هو إطار عمل كامل لإدارة محتوى الوسائط، مما يوفر ساعات من التطوير ويعزز أداء التطبيق.

\n\n

تثبيت Kingfisher

\n\n

يمكن تثبيت Kingfisher بعدة طرق. الطريقة الموصى بها هي عبر Swift Package Manager (SPM)، لأنها أداة أصلية لإدارة التبعيات في Swift.

\n\n

1. Swift Package Manager (SPM) — الطريقة الموصى بها

\n

افتح مشروعك في Xcode، وانتقل إلى File → Add Packages... والصق رابط المستودع:

\n

https://github.com/onevcat/Kingfisher.git

\n

اختر الإصدار (يوصى باستخدام "Up to Next Major Version" مع أحدث إصدار مستقر) وأضف الحزمة إلى هدفك.

\n\n

2. CocoaPods

\n

أضف إلى ملف Podfile الخاص بك:

\n

pod 'Kingfisher', '~> 7.0'

\n

ثم نفذ في الطرفية:

\n

pod install

\n\n

3. Carthage

\n

أضف إلى ملف Cartfile الخاص بك:

\n

github "onevcat/Kingfisher" ~> 7.0

\n

ثم نفذ:

\n

carthage update

\n\n

4. التثبيت اليدوي

\n

قم بتنزيل أحدث إصدار من GitHub وأضف الملفات من مجلد Sources/Kingfisher إلى مشروعك.

\n\n

بعد التثبيت، لا تنس استيراد المكتبة في الملفات التي تخطط لاستخدامها فيها:

\n

import Kingfisher

\n\n

بداية سريعة: المثال الأول

\n\n

لنبدأ بأبسط مثال — تحميل صورة من URL وعرضها في UIImageView. هذه هي العملية الأساسية التي تبدأ بها العمل مع Kingfisher.

\n\n

import UIKit\nimport Kingfisher\n\nclass ViewController: UIViewController {\n    @IBOutlet weak var imageView: UIImageView!\n    \n    override func viewDidLoad() {\n        super.viewDidLoad()\n        \n        let url = URL(string: "https://example.com/image.jpg")!\n        imageView.kf.setImage(with: url)\n    }\n}

\n\n

في هذا المثال، نستدعي طريقة setIm