عن المشروع
Kingfisher هي مكتبة قوية ومكتوبة بالكامل بلغة Swift لتنزيل الصور من الويب وتخزينها مؤقتًا. وهي توفر طريقة نقية بلغة Swift للتعامل مع الصور البعيدة في تطبيقك القادم.
## الميزات
- تنزيل الصور وتخزينها مؤقتًا بشكل غير متزامن.
- تحميل الصور إما من شبكات تعتمد على URLSession أو من بيانات محلية مقدمة.
- معالجات وفلاتر صور مفيدة مضمّنة.
- ذاكرة تخزين مؤقت هجينة متعددة الطبقات لكل من الذاكرة والقرص.
- تحكم دقيق في سلوك التخزين المؤقت مع تاريخ انتهاء وصلاحية حجم قابلين للتخصيص.
- فحص اختياري غير متزامن لذاكرة التخزين المؤقت في KingfisherManager لتجنب حجب خيط المستدعي عند فحوصات ذاكرة التخزين المؤقت على القرص.
- تنزيل قابل للإلغاء وإعادة استخدام تلقائية للمحتوى الذي تم تنزيله سابقًا لتحسين الأداء.
- مكونات مستقلة: استخدم أداة التنزيل ونظام التخزين المؤقت ومعالجات الصور بشكل منفصل حسب الحاجة.
- الجلب المسبق للصور وعرضها من ذاكرة التخزين المؤقت لتعزيز تطبيقك.
- امتدادات لـ UIImageView وNSImageView وNSButton وUIButton وNSTextAttachment وWKInterfaceImage وTVMonogramView وCPListItem لتعيين صورة مباشرة من عنوان URL.
- حركة انتقال مدمجة عند تعيين الصور.
- عنصر نائب ومؤشر قابلان للتخصيص أثناء تحميل الصور.
- معالجة صور وتنسيق صور قابلان للتوسيع بسهولة.
- دعم وضع البيانات المنخفضة.
- دعم SwiftUI.
- مُهيأ لـ Swift 6 وSwift Concurrency (الوضع الصارم).
- تحميل وتخزين مؤقت لـ Live Photo.
## Kingfisher 101
أبسط حالة استخدام هي تعيين صورة إلى عرض صورة باستخدام امتداد UIImageView:
```swift
import Kingfisher
let url = URL(string: "https://example.com/image.png")
imageView.kf.setImage(with: url)
```
ستقوم Kingfisher بتنزيل الصورة من url، وإرسالها إلى كل من ذاكرة التخزين المؤقت في الذاكرة وذاكرة التخزين المؤقت على القرص، وعرضها في imageView. وعند تعيينها بنفس عنوان URL لاحقًا، سيتم استرجاع الصورة من ذاكرة التخزين المؤقت وعرضها فورًا.
كما تعمل أيضًا إذا كنت تستخدم SwiftUI:
```swift
var body: some View {
KFImage(URL(string: "https://example.com/image.png")!)
}
```
## مثال أكثر تقدمًا
مع الخيارات القوية، يمكنك إنجاز مهام صعبة باستخدام Kingfisher بطريقة بسيطة. على سبيل المثال، الكود أدناه:
1. ينزّل صورة عالية الدقة.
2. يقلل دقتها لتطابق حجم عرض الصورة.
3. يجعلها ذات زوايا دائرية بنصف قطر معين.
4. يعرض مؤشرًا نظاميًا وصورة عنصر نائب أثناء التنزيل.
5. عند الجهوزية، يحرّك الصورة المصغرة الصغيرة بتأثير "تلاشٍ تدريجي".
6. يتم أيضًا تخزين الصورة الكبيرة الأصلية مؤقتًا على القرص لاستخدامها لاحقًا، لتجنب تنزيلها مرة أخرى في عرض التفاصيل.
7. تُطبع سجلات وحدة التحكم عند انتهاء المهمة، سواء للنجاح أو الفشل.
```swift
let url = URL(string: "https://example.com/high_resolution_image.png")
let processor = DownsamplingImageProcessor(size: imageView.bounds.size)
|> RoundCornerImageProcessor(cornerRadius: 20)
imageView.kf.indicatorType = .activity
imageView.kf.setImage(
with: url,
placeholder: UIImage(named: "placeholderImage"),
options: [
.processor(processor),
.scaleFactor(UIScreen.main.scale),
.transition(.fade(1)),
.cacheOriginalImage
])
{
result in
switch result {
case .success(let value):
print("Task done for: \(value.source.url?.absoluteString ?? "")")
case .failure(let error):
print("Job failed: \(error.localizedDescription)")
}
}
```
هذه حالة شائعة يمكن أن أواجهها في عملي اليومي. فكّر في عدد الأسطر التي ستحتاج إلى كتابتها بدون Kingfisher!
## تسلسل الاستدعاءات
إذا لم تكن من محبي امتداد kf، يمكنك أيضًا تفضيل استخدام منشئ KF وتسلسل استدعاءات الدوال. الكود أدناه يقوم بالشيء نفسه:
```swift
// Use `kf` extension
imageView.kf.setImage(
with: url,
placeholder: placeholderImage,
options: [
.processor(processor),
.loadDiskFileSynchronously,
.cacheOriginalImage,
.transition(.fade(0.25)),
.lowDataMode(.network(lowResolutionURL))
],
progressBlock: { receivedSize, totalSize in
// Progress updated
},
completionHandler: { result in
// Done
}
)
// Use `KF` builder
KF.url(url)
.placeholder(placeholderImage)
.setProcessor(processor)
.loadDiskFileSynchronously()
.cacheMemoryOnly()
.fade(duration: 0.25)
.lowDataModeSource(.network(lowResolutionURL))
.onProgress { receivedSize, totalSize in }
.onSuccess { result in }
.onFailure { error in }
.set(to: imageView)
```
والأفضل من ذلك، إذا أردت لاحقًا التبديل إلى SwiftUI، فما عليك سوى تغيير KF أعلاه إلى KFImage، وقد انتهيت:
```swift
struct ContentView: View {
var body: some View {
KFImage.url(url)
.placeholder(placeholderImage)
.setProcessor(processor)
.loadDiskFileSynchronously()
.cacheMemoryOnly()
.fade(duration: 0.25)
.lowDataModeSource(.network(lowResolutionURL))
.onProgress { receivedSize, totalSize in }
.onSuccess { result in }
.onFailure { error in }
}
}
```
## المتطلبات
### فرع التطوير الحالي
- iOS 15.0+ / macOS 12.0+ / tvOS 15.0+ / watchOS 9.0+ / visionOS 1.0+
- Xcode 26.0+ / مترجم Swift 6.2+
### Kingfisher 8.0
- (UIKit/AppKit) iOS 13.0+ / macOS 10.15+ / tvOS 13.0+ / watchOS 6.0+ / visionOS 1.0+
- (SwiftUI) iOS 14.0+ / macOS 11.0+ / tvOS 14.0+ / watchOS 7.0+ / visionOS 1.0+
- Swift 5.9+
### Kingfisher 7.0
- (UIKit/AppKit) iOS 12.0+ / macOS 10.14+ / tvOS 12.0+ / watchOS 5.0+ / visionOS 1.0+
- (SwiftUI) iOS 14.0+ / macOS 11.0+ / tvOS 14.0+ / watchOS 7.0+ / visionOS 1.0+
- Swift 5.0+
## التثبيت
راجع أحد الدروس التالية لتثبيت الإطار واستخدامه:
- [UIKit Tutorial](https://swiftpackageindex.com/onevcat/kingfisher/master/tutorials/kingfisher/gettingstarteduikit)
- [SwiftUI Tutorial](https://swiftpackageindex.com/onevcat/kingfisher/master/tutorials/kingfisher/gettingstartedswiftui)
بدلاً من ذلك، يمكنك اتباع أي من الطرق أدناه.
### Swift Package Manager
- File > Swift Packages > Add Package Dependency
- Add `https://github.com/onevcat/Kingfisher.git`
- Select "Up to Next Major" with "8.0.0"
### CocoaPods
```ruby
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '13.0'
use_frameworks!
target 'MyApp' do
pod 'Kingfisher', '~> 8.0'
end
```
### إطار مسبق البناء
1. افتح صفحة الإصدارات، ونزّل أحدث إصدار من Kingfisher من قسم الأصول.
2. اسحب `Kingfisher.xcframework` إلى مشروعك وأضفه إلى الهدف (عادةً هدف التطبيق).
3. اختر هدفك، وفي تبويب "General"، ابحث عن قسم "Frameworks, Libraries, and Embedded Content"، واضبط `Embed Without Signing` إلى Kingfisher.
## التوثيق
راجع التوثيق والدروس:
- [Documentation Home](https://swiftpackageindex.com/onevcat/kingfisher/master/documentation/kingfisher)
- [Getting Started](https://swiftpackageindex.com/onevcat/kingfisher/master/documentation/kingfisher/gettingstarted)
- [UIKit Tutorial](https://swiftpackageindex.com/onevcat/kingfisher/master/tutorials/kingfisher/gettingstarteduikit)
- [SwiftUI Tutorial](https://swiftpackageindex.com/onevcat/kingfisher/master/tutorials/kingfisher/gettingstartedswiftui)
- [Common Tasks - General](https://swiftpackageindex.com/onevcat/kingfisher/master/documentation/kingfisher/commontasks)
- [Common Tasks - Cache](https://swiftpackageindex.com/onevcat/kingfisher/master/documentation/kingfisher/commontasks_cache)
- [Common Tasks - Downloader](https://swiftpackageindex.com/onevcat/kingfisher/master/documentation/kingfisher/commontasks_downloader)
- [Common tasks - Processor](https://swiftpackageindex.com/onevcat/kingfisher/master/documentation/kingfisher/commontasks_processor)
### الترحيل
- [Kingfisher 8.0 Migration](https://swiftpackageindex.com/onevcat/kingfisher/master/documentation/kingfisher/migration-to-8)
- [Kingfisher 7.0 Migration](https://github.com/onevcat/Kingfisher/wiki/Kingfisher-7.0-Migration-Guide)
إذا كنت تستخدم إصدارًا أقدم، فراجع الأدلة أدناه لمعرفة خطوات الترحيل.
## أخرى
### مستقبل Kingfisher
أريد إبقاء Kingfisher خفيفة. يركز هذا الإطار على توفير حل بسيط لتنزيل الصور وتخزينها مؤقتًا. هذا لا يعني أن الإطار لا يمكن تحسينه. Kingfisher بعيدة عن الكمال، لذا سيتم إجراء تحديثات ضرورية ومفيدة لجعلها أفضل.
### التطوير والاختبارات
أي مساهمات وطلبات سحب مرحب بها بحرارة. ومع ذلك، قبل أن تخطط لتنفيذ بعض الميزات أو محاولة إصلاح مشكلة غير مؤكدة، يُوصى بفتح نقاش أولاً. سيكون من الرائع إذا كانت طلبات السحب الخاصة بك تُبنى مع نجاح جميع الاختبارات. :)
### حول الشعار
شعار Kingfisher مستوحى من Tangram (七巧板)، وهي أحجية تفكيك تتكون من سبعة أشكال مسطحة من الصين. أعتقد أنها طائر رفيع (kingfisher) وليس سمامة (swift)، لكن البعض يصر على أنها حمامة. أظن أنه يجب أن أعطيها اسمًا. مرحبًا يا رفاق، هل لديكم أي اقتراحات؟
### التواصل
تابعني وتواصل معي على Twitter أو Sina Weibo. إذا وجدت مشكلة، افتح تذكرة. طلبات السحب مرحب بها بحرارة أيضًا.
## الداعمون والرعاة
لا يمكن للمشاريع مفتوحة المصدر أن تعيش طويلاً بدون مساعدتك. إذا وجدت Kingfisher مفيدة، فيرجى التفكير في دعم هذا المشروع من خلال أن تصبح راعيًا. تظهر أيقونة المستخدم أو شعار شركتك على مدونتي مع رابط إلى صفحتك الرئيسية.
كن راعيًا عبر GitHub Sponsors. :heart:
شكر خاص لـ imgly وemergetools.
### الترخيص
يتم إصدار Kingfisher بموجب ترخيص MIT. راجع LICENSE للتفاصيل.
Comments
0 people shared their preference · Deer Point appears after 10 participants
Sign in to join the discussion.