Photo Editing Extension: چیست، قابلیت‌های افزونه برای iOS

Photo Editing Extension در iOS چیست

Photo Editing Extension — نوعی افزونه برنامه در iOS است که ابزارهای پردازش تصویر را به رابط استاندارد برنامه Photos وارد می‌کند. کاربر تصویر را باز می‌کند، دکمه «ویرایش» را فشار می‌دهد و افزونه مورد نظر را از لیست افزونه‌های نصب شده انتخاب می‌کند. پس از ویرایش، نتیجه به کتابخانه بازگردانده می‌شود و فایل اصلی برای بازگردانی در دسترس باقی می‌ماند.

این معماری مشکل کلیدی تجربه کاربری را حل می‌کند: نیازی به جابجایی بین برنامه‌ها، صادرات و واردات تصاویر و پیگیری نسخه‌ها نیست. به گفته WWDC 2025، همه افزونه‌ها در یک فرایند ایزوله با سندباکس مخصوص و زمان اجرای محدود — تا ۳۰ ثانیه برای هر عملیات ویرایش — کار می‌کنند.

افزونه به فایل‌های دلخواه در حافظه دستگاه دسترسی ندارد — فقط به تصویری که کاربر به صراحت از طریق رابط انتخاب منتقل کرده است. این امر امنیت داده‌های کاربر را هنگام استفاده از ابزارهای شخص ثالث تضمین می‌کند.

PhotoKit: معماری و مؤلفه‌های کلیدی

PhotoKit — فریمورک اپل برای کار با کتابخانه رسانه‌ای دستگاه است که در iOS 8 معرفی شد. این فریمورک دسترسی برنامه‌نویسی به منابع Photos از جمله تصاویر، ویدئوها، آلبوم‌ها و فراداده را فراهم می‌کند. برای افزونه‌های ویرایش، PhotoKit به عنوان لایه میانی بین ذخیره‌ساز و رابط تغییر عمل می‌کند.

PHAsset و PHAssetResource

PHAsset یک شی رسانه‌ای جداگانه در کتابخانه — تصویر یا ویدئو — را نشان می‌دهد. از طریق PHAsset می‌توان فراداده را به دست آورد: تاریخ عکاسی، نوع فایل، موقعیت روی نقشه و جهت دوربین. PHAssetResource به منابع پایه دسترسی می‌دهد — مثلاً به فایل اصلی تصویر در فرمت RAW یا HEIC.

برای افزونه ویرایش، PHContentEditingInput حیاتی است — شیءای که فایل کامل تصویر (یا ویدئو) را برای خواندن و پردازش در دسترس قرار می‌دهد. افزونه این شیء را در زمان فعال‌سازی دریافت می‌کند و از آن به عنوان ماده اولیه استفاده می‌کند.

PHImageManager و حافظه نهان

PHImageManager بارگذاری و ذخیره‌سازی تصاویر را مدیریت می‌کند. برای افزونه ویرایش مستقیماً استفاده نمی‌شود — افزونه فایل کامل را از طریق PHContentEditingInput دریافت می‌کند. با این حال PHImageRequestOptions امکان پیکربندی پارامترهای درخواست را فراهم می‌کند: اندازه، نوع تحویل (همزمان یا ناهمزمان) و فرمت نتیجه.

به گفته اپل، PHImageManager به طور خودکار تصاویر کوچک را در حافظه RAM ذخیره می‌کند که نمایش مجدد پیش‌نمایش‌ها را سرعت می‌بخشد. برای افزونه ویرایش توصیه می‌شود از PHImageRequestOptionsDeliveryModeHighQualityFormat استفاده کنید تا بهترین کیفیت تصویر به دست آید.

let options = PHImageRequestOptions()
options.deliveryMode = .highQualityFormat
options.isSynchronous = true

PHImageManager.default().requestImage(
    for: asset,
    targetSize: .init(width: 1024, height: 1024),
    contentMode: .aspectFill,
    options: options
) { image, _ in
    // استفاده از تصویر برای نمایش
}

ایجاد افزونه: PHContentEditingController

هر Photo Editing Extension پروتکل PHContentEditingController را پیاده‌سازی می‌کند — عنصر مرکزی کنترل افزونه. این پروتکل روش‌هایی برای نمایش رابط، دریافت داده‌های ورودی و ذخیره نتیجه تعریف می‌کند.

روش‌های اصلی پروتکل

beginContentEditing(with:) هنگام شروع جلسه ویرایش فراخوانی می‌شود. افزونه PHContentEditingInput را دریافت می‌کند و باید رابط را با تصویر اصلی نمایش دهد. finishContentEditing(completionHandler:) ویرایش را پایان می‌دهد — افزونه PHContentEditingOutput را با فایل تغییر یافته و AdjustmentData برمی‌گرداند. cancelContentEditing() تغییرات را بدون ذخیره لغو می‌کند.

نکته مهم: در زمان فراخوانی beginContentEditing افزونه فقط به یک نسخه از تصویر دسترسی دارد — همان نسخه‌ای که کاربر درخواست کرده است. نمی‌توان به تصویر یا آلبوم دیگری دسترسی پیدا کرد. این محدودیت سندباکس است که توسط اپل برای امنیت اعمال شده است.

class PhotoEditingViewController: UIViewController {

    override func beginContentEditing(
        with input: PHContentEditingInput
    ) {
        guard let url = input.fullSizeImageURL else { return }
        let image = CIImage(contentsOf: url)
        displayImage.image = UIImage(ciImage: image)
    }
}

معماری جداسازی

PHContentEditingController رابط ویرایش را از منطق ذخیره‌سازی جدا می‌کند. فرایند اصلی iOS beginContentEditing را فراخوانی می‌کند، افزونه رابط کاربری خود را نشان می‌دهد، کاربر تغییرات را اعمال می‌کند، سپس finishContentEditing یک فایل جدید ایجاد می‌کند. اپل توصیه می‌کند تمام پردازش‌های سنگین — فیلترهای CIFilter، دستکاری‌های Core Image — را در پس‌زمینه انجام دهید نه در نخ اصلی، تا رابط کاربری مسدود نشود.

ویرایش غیرمخرب از طریق AdjustmentData

PHAdjustmentData — مکانیزم کلیدی برای ویرایش غیرمخرب در Photo Editing Extension است. این شیء حاوی اطلاعاتی درباره تغییرات اعمال شده در قالبی دلخواه است. افزونه پارامترهای فیلترها، ماسک‌ها و تنظیمات را در AdjustmentData سریال‌سازی می‌کند و همراه با تصویر تغییر یافته ذخیره می‌کند.

هنگام باز کردن مجدد تصویر، افزونه AdjustmentData را می‌خواند، وضعیت قبلی رابط را بازیابی می‌کند و به کاربر اجازه می‌دهد ویرایش را از همان نقطه ادامه دهد. اگر افزونه نصب نباشد — تصویر در آخرین نسخه ذخیره شده نمایش داده می‌شود و اصل تصویر جداگانه نگهداری می‌شود.

به گفته Apple Documentation، PHAdjustmentData formatIdentifier و formatVersion را ذخیره می‌کند — رشته‌هایی برای شناسایی قالب داده. هنگام به‌روزرسانی افزونه باید نسخه را بررسی کرده و قالب‌های قدیمی را به درستی پردازش کرد.

let adjustmentData = PHAdjustmentData(
    formatIdentifier: "com.example.photoediting",
    formatVersion: "1.0",
    data: NSKeyedArchiver.archivedData(
        withRootObject: params,
        requiringSecureCoding: true
    )
)
output.adjustmentData = adjustmentData

در زمان finishContentEditing افزونه AdjustmentData را در شیء PHContentEditingOutput همراه با فایل تصویر تغییر یافته می‌نویسد. سیستم سپس هر دو مؤلفه را ذخیره می‌کند: نسخه برای نمایش و فراداده برای بازیابی جلسه ویرایش.

ادغام با برنامه Photos

Photo Editing Extension پس از نصب برنامه حاوی آن به طور خودکار در منوی برنامه Photos ظاهر می‌شود. کاربر تصویر را باز می‌کند، «ویرایش» را انتخاب می‌کند و در ردیف پایین ابزارها، همه افزونه‌های ویرایش نصب شده — هم سیستمی و هم شخص ثالث — نمایش داده می‌شوند.

ثبت افزونه

افزونه از طریق Info.plist برنامه اصلی با کلید NSExtensionActivationRule ثبت می‌شود که مشخص می‌کند چه نوع محتوایی افزونه را فعال می‌کند. برای ویرایشگر عکس، ActivationRule معمولاً به image نیاز دارد — افزونه برای ویدئو یا عکس‌های زنده نمایش داده نمی‌شود.

اپل توصیه می‌کند انواع فعال‌سازی خاصی را مشخص کنید تا منوی ویرایش شلوغ نشود. اگر افزونه فقط از JPEG و HEIC پشتیبانی می‌کند، بهتر است فعال‌سازی را به این فرمت‌ها محدود کنید.

<!-- Info.plist -->
<key>NSExtension</key>
<dict>
    <key>NSExtensionPointIdentifier</key>
    <string>com.apple.photo-editing</string>
    <key>NSExtensionActivationRule</key>
    <string>SUBQUERY (extensionItems,
        @count <= 1)</string>
</dict>

تعامل با کاربر

پس از انتخاب افزونه، iOS یک فرایند جداگانه با UIViewController سفارشی ایجاد می‌کند که روی رابط Photos نمایش داده می‌شود. کاربر تصویر خود، ابزارهای افزونه و دکمه‌های «لغو» / «انجام شد» را می‌بیند. افزونه نمی‌تواند ناوبری خارج از کنترلر خود را تغییر دهد یا به بخش‌های دیگر سیستم دسترسی پیدا کند.

به گفته Human Interface Guidelines اپل، رابط افزونه باید حداقلی و کاربردی باشد — بدون تبلیغات، لینک‌های خارجی و عناصر ناوبری اضافی. توصیه می‌شود از UIScrollView برای نمایش پالت ابزارها استفاده کنید تا صفحه شلوغ نشود.