PhotoKit — چیست، مفاهیم کلیدی و PHAsset

PhotoKit چیست؟

PhotoKit — فریم‌ورک اپل (معرفی‌شده در iOS 8، macOS 10.11) که یک API شیء‌گرا برای کار با کتابخانه رسانه سیستمی فراهم می‌کند. برخلاف AssetsLibrary، PhotoKit با کتابخانه رسانه مانند یک پایگاه داده کار می‌کند: پرس‌وجوها اشیاء PHAsset، PHCollection، PHCollectionList را برمی‌گردانند که محتوا و ساختار ذخیره‌سازی را نمایش می‌دهند.

PhotoKit از همه انواع رسانه پشتیبانی می‌کند: عکس‌ها (JPEG، HEIF، RAW)، ویدیوها (MOV، MP4)، Live Photos و عکس‌های پشت‌سرهم. فریم‌ورک به طور خودکار همگام‌سازی iCloud را مدیریت می‌کند: اگر تصویر در iCloud ذخیره شده باشد، PhotoKit آن را از طریق شبکه درخواست کرده و پیشرفت را از طریق PHImageRequestOptions.progressHandler گزارش می‌دهد.

ویژگی کلیدی PhotoKit — مدل داده مبتنی بر PHObject با شناسه محلی (localIdentifier) است که بین جلسات پایدار می‌ماند. این امکان ذخیره ارجاعات به اشیاء رسانه‌ای و بازیابی آنها پس از راه‌اندازی مجدد برنامه بدون پرس‌وجوی مجدد را فراهم می‌کند.

PhotoKit چگونه کار می‌کند: مدل داده و پرس‌وجوها

PhotoKit در سه سطح ساخته شده است: مدل داده (PHObject)، پرس‌وجوها (PHFetchResult) و تغییرات (PHPhotoLibrary.performChanges). مدل داده سلسله‌مراتبی است: PHAsset (عکس/ویدیو) در داخل PHAssetCollection (آلبوم) قرار دارد، آلبوم‌ها در PHCollectionList (پوشه) گروه‌بندی می‌شوند.

اجرای پرس‌وجوها

پرس‌وجوها از طریق PHAsset.fetchAssets و PHAssetCollection.fetchAssetCollections اجرا می‌شوند. همه متدهای fetch همزمان هستند و PHFetchResult را برمی‌گردانند که شیء آن بلافاصله پرس‌وجو را به پایگاه داده کتابخانه رسانه اجرا می‌کند. PHFetchResult از دسترسی سریع بر اساس ایندکس (object(at:)) و شمارش از طریق enumerateObjects پشتیبانی می‌کند.

• fetchAssets(with:options:) — پرس‌وجوی همه رسانه‌ها با فیلتر بر اساس نوع، تاریخ، آلبوم
• fetchAssetCollections(with:subtype:options:) — پرس‌وجوی آلبوم‌ها و پوشه‌ها
• fetchAssets(in:options:) — پرس‌وجوی رسانه‌ها در داخل یک آلبوم مشخص

PHFetchOptions

PHFetchOptions — شیء برای پیکربندی پرس‌وجو: مرتب‌سازی (sortDescriptors)، گزاره (predicate)، شامل‌کردن رسانه‌های مخفی و حذف‌شده (includeHiddenAssets، includeAllBurstAssets). گزینه‌های fetch امکان فیلتر بر اساس نوع رسانه را فراهم می‌کنند: PHAssetMediaType.image، .video، .audio.

کلاس‌های اصلی PhotoKit

PhotoKit شامل مجموعه‌ای از کلاس‌ها برای دسترسی، پرس‌وجو و تغییر کتابخانه رسانه است. درک هر یک از آنها برای کار مؤثر با فریم‌ورک ضروری است.

PHAsset

PHAsset — شیء تغییرناپذیر که یک محتوای رسانه‌ای را نمایش می‌دهد. شامل فراداده: mediaType، mediaSubtypes، creationDate، location، pixelWidth، pixelHeight، duration (برای ویدیو)، isFavorite، burstIdentifier. LocalIdentifier — کلید متنی پایدار که حتی پس از راه‌اندازی مجدد برنامه در دسترس است.

PHAssetCollection

PHAssetCollection — گروه رسانه: آلبوم‌های سیستمی (Recents، Favorites، Selfies، Screenshots)، آلبوم‌های کاربر یا Moments (گروه‌بندی خودکار بر اساس زمان و مکان). ویژگی‌ها: localizedTitle، assetCollectionType، assetCollectionSubtype، startDate، endDate.

PHCollectionList

PHCollectionList — پوشه‌ای شامل آلبوم‌ها (PHAssetCollection) یا پوشه‌های دیگر. به ندرت استفاده می‌شود، عمدتاً برای نمایش سلسله‌مراتب در رابط کاربری.

PHImageManager و کش‌کردن

PhotoKit UIImage را مستقیماً از PHAsset برنمی‌گرداند — باید تصویر را از طریق PHImageManager درخواست کرد. این تضمین می‌کند که تصویر با در نظر گرفتن iCloud، کش‌کردن و اندازه مورد نیاز بارگذاری می‌شود.

PHImageManager از سه حالت تحویل پشتیبانی می‌کند: opportunistic (ابتدا نسخه کوچک‌شده، سپس کامل)، highQualityFormat (فقط کیفیت کامل) و fastFormat (سریع‌ترین نسخه موجود). برای مجموعه‌ها همیشه از PHCachingImageManager با پیش‌بارگذاری تصاویر برای سلول‌های قابل مشاهده استفاده کنید.

نمونه‌های استفاده از PhotoKit در Swift

PhotoKit برای ایجاد گالری‌های سفارشی، ویرایشگرها و برنامه‌های کار با رسانه استفاده می‌شود. سه سناریوی کلیدی را بررسی می‌کنیم.

پرس‌وجوی همه عکس‌ها از کتابخانه رسانه

PHAsset.fetchAssets با PHFetchOptions و مرتب‌سازی بر اساس تاریخ ایجاد — پرس‌وجوی پایه برای ساخت گالری عکس سفارشی. PHFetchResult از بارگذاری تنبل و دسترسی جریانی پشتیبانی می‌کند.

let options = PHFetchOptions()
options.sortDescriptors = [NSSortDescriptor(
    key: "creationDate",
    ascending: .false
)]
options.predicate = NSPredicate(
    format: "mediaType == %d",
    PHAssetMediaType.image.rawValue
)

let allPhotos = PHAsset.fetchAssets(with: options)
print("تعداد \(allPhotos.count) عکس پیدا شد")

allPhotos.enumerateObjects { asset, index, stop in
    print("عکس \(index): \(asset.localIdentifier)")
}

PHFetchResult — ظرف ایمن برای نخ. دسترسی به اشیاء بر اساس ایندکس از طریق object(at:) UI را مسدود نمی‌کند، اما درخواست تصویر از طریق PHImageManager باید به صورت ناهمزمان انجام شود.

بارگذاری تصویر با کش

PHCachingImageManager — زیرکلاس PHImageManager با متدهای startCachingImages و stopCachingImages برای پیش‌بارگذاری. در UICollectionView برای اسکرول روان استفاده می‌شود.

let cachingManager = PHCachingImageManager()
let targetSize = CGSize(width: 200, height: 200)

// پیش‌بارگذاری برای سلول‌های قابل مشاهده
cachingManager.startCachingImages(
    for: visibleAssets,
    targetSize: targetSize,
    contentMode: .aspectFill,
    options: nil
)

// درخواست تصویر از طریق PHImageRequestOptions با fallback iCloud
let requestOptions = PHImageRequestOptions()
requestOptions.deliveryMode = .opportunistic
requestOptions.isNetworkAccessAllowed = .true
requestOptions.progressHandler = { progress, error, stop, info in
    DispatchQueue.main.async {
        print("در حال بارگذاری از iCloud: \(progress * 100)%")
    }
}

let requestID = cachingManager.requestImage(
    for: asset,
    targetSize: targetSize,
    contentMode: .aspectFill,
    options: requestOptions
) { image, info in
    print("تصویر دریافت شد: \(image?.size ?? .zero)")
}

ویرایش کتابخانه رسانه: افزودن به موارد دلخواه

تغییرات در کتابخانه رسانه از طریق PHPhotoLibrary.shared().performChanges در داخل بلاک changeRequest انجام می‌شود. همه عملیات دسته‌بندی شده و به صورت تراکنشی اعمال می‌شوند.

PHPhotoLibrary.shared().performChanges {
    let changeRequest = PHAssetChangeRequest(for: asset)
    changeRequest.isFavorite = .true
} completionHandler: { success, error in
    if success {
        print("به موارد دلخواه اضافه شد")
    }
}

تغییرات و مشاهده از طریق Change Tracking

PhotoKit مکانیزم مشاهده تغییرات در کتابخانه رسانه را از طریق پروتکل PHPhotoLibraryChangeObserver فراهم می‌کند. در هر تغییری (ایجاد، حذف، ویرایش) متد photoLibraryDidChange با شیء PHChange فراخوانی می‌شود.

PHChange شامل changeDetails برای هر نوع پرس‌وجو است: PHFetchResultChangeDetails با removedIndexes، insertedIndexes، changedIndexes. این امکان اعمال تغییرات در UI با انیمیشن را فراهم می‌کند: performBatchUpdates با move، insert، delete برای UICollectionView.

class PhotosViewController: UIViewController {
    var fetchResult: PHFetchResult>PHAsset>?

    override func viewDidLoad() {
        super.viewDidLoad()
        PHPhotoLibrary.shared().register(self)
    }

    deinit {
        PHPhotoLibrary.shared().unregisterChangeObserver(self)
    }
}

extension PhotosViewController: PHPhotoLibraryChangeObserver {
    func photoLibraryDidChange(_ changeInstance: PHChange) {
        guard let fetchResult,
              let details = changeInstance.changeDetails(for: fetchResult)
        else { return }

        DispatchQueue.main.async {
            self.fetchResult = details.fetchResultAfterChanges
            // اعمال تغییرات به collectionView
        }
    }
}

ویرایش RAW و افزونه‌ها

PhotoKit از ویرایش رسانه از طریق مکانیزم PHContentEditingInput و PHContentEditingOutput پشتیبانی می‌کند. برنامه editingInput را با داده‌های اصلی درخواست می‌کند، تغییرات را اعمال کرده و نتیجه را از طریق editingOutput ذخیره می‌کند. فریم‌ورک به طور خودکار نسخه اصلی را حفظ می‌کند و به کاربر امکان بازگرداندن تغییرات را از طریق بازنشانی به نسخه اصلی می‌دهد.

عکس‌های RAW (DNG، CR2، NEF) از طریق PHAssetResourceManager پشتیبانی می‌شوند که دسترسی به فایل RAW اصلی را فراهم می‌کند. برای پردازش RAW توصیه می‌شود از CoreImage با فیلتر CIRAWFilter استفاده کنید که از تنظیم دما، نوردهی و وضوح پشتیبانی می‌کند. PhotoKit همچنین از افزونه‌های ویرایشگر از طریق Photo Editing Extension (iOS) پشتیبانی می‌کند — برنامه می‌تواند از ویرایشگر سیستم برای پردازش عکس یا ویدیوی انتخاب‌شده فراخوانی شود.

بهینه‌سازی کار با PhotoKit

PhotoKit — فریم‌ورک قدرتمند اما منابعی. استفاده نادرست می‌تواند منجر به کندی هنگام اسکرول و مصرف بیش از حد حافظه شود. برای عملکرد بهینه توصیه‌ها را دنبال کنید.

• از PHCachingImageManager استفاده کنید برای مجموعه‌ها — پیش‌بارگذاری تصاویر برای سلول‌های قابل مشاهده +-1 صفحه تأخیر هنگام اسکرول را از بین می‌برد
• targetSize را تنظیم کنید — هرگز برای تصاویر بند انگشتی PHImageManagerMaximumSize درخواست نکنید. از اندازه‌ای برابر با اندازه فیزیکی سلول ضرب‌در scale صفحه استفاده کنید
• پرس‌وجوها را لغو کنید هنگام استفاده مجدد از سلول — PHImageRequestID را ذخیره کرده و در prepareForReuse cancelImageRequest را فراخوانی کنید
• پرس‌وجوهای iCloud را محدود کنید — هنگام اسکرول سریع isNetworkAccessAllowed = false تنظیم کرده و عکس‌های iCloud را فقط در هنگام توقف بارگذاری کنید
• PHFetchResult را کش کنید — fetchAssets مکرر با همان گزینه‌ها یک PHFetchResult جدید برمی‌گرداند. نتیجه را در ویژگی ذخیره کرده و از طریق Change Observer به‌روزرسانی کنید

PHLivePhoto — نیاز به پرس‌وجوی جداگانه از طریق PHLivePhoto.request(with:targetSize:contentMode:options:resultHandler:) دارد. برای سلول‌هایی که فقط عکس نمایش می‌دهند Live Photo درخواست نکنید — از PHLivePhotoBadge برای نشان‌دادن استفاده کنید.