Action Extension: چیست، چگونه کار می‌کند و توسعه افزونه

Action Extension چیست

Action Extension — نوعی افزونه iOS است که به شما امکان می‌دهد مستقیماً در زمینه برنامه میزبان بر روی محتوا اقدام کنید. کاربر متنی را در Safari انتخاب می‌کند، دکمه «اقدامات» را فشار می‌دهد و مثلاً «بررسی املا» را انتخاب می‌کند — افزونه متن را پردازش می‌کند و نتیجه را بدون ترک مرورگر بازمی‌گرداند. افزونه داده‌های ورودی را از طریق NSExtensionContext دریافت می‌کند و می‌تواند محتوای تغییر یافته را بازگرداند.

Action Extension در iOS 8 به عنوان بخشی از معماری افزونه‌های برنامه ظاهر شد. ویژگی کلیدی آن این است که افزونه رابط کاربری خود را ندارد (اختیاری) و در زمینه برنامه میزبان اجرا می‌شود. کاربر صفحه فعلی را ترک نمی‌کند که حداقل وقفه شناختی را تضمین می‌کند. به گفته Apple، Action Extension تنها نوع افزونه‌ای است که می‌تواند همزمان محتوای برنامه میزبان را بخواند و تغییر دهد (از طریق NSExtensionContext با بازگرداندن نتیجه).

Action Extension در کجا استفاده می‌شود

Action Extension در سناریوهای مختلفی استفاده می‌شود: ترجمه متن در مرورگر، ایجاد PDF از صفحه وب، اعمال فیلتر بر روی عکس در گالری، بررسی املا در هر فیلد متنی، کوتاه‌سازی URL، رمزگذاری متن و افزودن به نشانک‌ها. جهانی بودن Action Extension آن را به ابزاری محبوب برای برنامه‌های دسته «ابزارها» و «بهره‌وری» تبدیل کرده است.

Action Extension در مقابل Share Extension

Action Extension و Share Extension اغلب اشتباه گرفته می‌شوند، اما هدف آنها اساساً متفاوت است. Share Extension محتوا را از برنامه میزبان به برنامه شما ارسال می‌کند؛ Action Extension محتوا را پردازش می‌کند و آن را بازمی‌گرداند. تفاوت بر معماری، تجربه کاربری و الزامات پیکربندی Info.plist تأثیر می‌گذارد.

کاربر چگونه اقدام را انتخاب می‌کند

Action Extension در منوی اقدامات (Action Sheet) با فشار دادن دکمه «اشتراک‌گذاری» یا «...» ظاهر می‌شود. iOS به طور خودکار Action Extensions را در بخش بالایی برگه (اقدامات) و Share Extensions را در بخش پایینی (برنامه‌ها) قرار می‌دهد. سناریوی کاربر: متن را انتخاب کرد → «اقدامات» را فشار داد → Action Extension شما را انتخاب کرد → نتیجه پردازش‌شده را بدون تغییر برنامه دریافت کرد.

معماری Action Extension

Action Extension از یک target در Xcode، UIViewController برای نمایش رابط (اختیاری)، NSExtensionContext برای ورودی-خروجی داده و پیکربندی Info.plist تشکیل شده است. معماری ساده‌تر از Share Extension است: هیچ رابط compose اجباری وجود ندارد و افزونه می‌تواند کاملاً بدون UI کار کند.

اجزای Action Extension

Target — یک باندل جداگانه با شناسه‌ای که از برنامه اصلی به ارث رسیده است. UIViewController — رابط اختیاری برای نمایش پیشرفت، تنظیمات یا نتیجه. NSExtensionContext — ظرفی با داده‌های ورودی (inputItems) و متد completeRequest برای بازگرداندن نتیجه. Info.plist — پیکربندی فعال‌سازی از طریق NSExtensionActivationRule و ویژگی‌ها (NSExtensionAttributes) برای مشخص کردن انواع محتوای پشتیبانی‌شده.

NSExtensionContext و جریان‌های داده

Action Extension داده‌های ورودی را از طریق extensionContext?.inputItems دریافت می‌کند — آرایه‌ای از NSExtensionItem. هر عنصر شامل پیوست‌هایی با داده و UTI است. پس از پردازش، افزونه completeRequest(returningItems:) را با آرایه‌ای از NSExtensionItem خروجی فراخوانی می‌کند. برنامه میزبان داده‌های پردازش‌شده را دریافت کرده و نمایش می‌دهد. مدل ناهمگام: افزونه می‌تواند عملیات طولانی را انجام دهد و زمینه را تا 30 ثانیه نگه دارد.

ایجاد Action Extension

ایجاد Action Extension در Swift برای ترجمه متن انتخاب‌شده را بررسی می‌کنیم. افزونه متن را از برنامه میزبان دریافت می‌کند، آن را به سرور ترجمه ارسال می‌کند و نتیجه را بازمی‌گرداند. ActionViewController — کنترلر پایه‌ای که Xcode هنگام افزودن target ایجاد می‌کند.

import UIKit
import MobileCoreServices

class ActionViewController: UIViewController {

    @IBOutlet var resultLabel: UILabel!

    override func viewDidLoad() {
        super.viewDidLoad()
        extractTextAndTranslate()
    }

    func extractTextAndTranslate() {
        guard let item = extensionContext?.inputItems.first
                as? NSExtensionItem
        else { return }

        for attachment in item.attachments ?? [] {
            attachment.loadItem(
                forTypeIdentifier: kUTTypePlainText as String
            ) { [weak self] (text, error) in
                guard let inputText = text as? String else { return }
                TranslationService().translate(inputText, from: "en", to: "ru") {
                    translated in
                    DispatchQueue.main.async {
                        self?.resultLabel?.text = translated
                    }
                }
            }
        }
    }
}

پس از پردازش، افزونه نتیجه را به برنامه میزبان بازمی‌گرداند. completeRequest با داده‌های خروجی — سناریوی جایگزین، زمانی که افزونه UI را نشان نمی‌دهد و بلافاصله محتوای پردازش‌شده را بازمی‌گرداند.

// بازگرداندن متن پردازش‌شده به برنامه میزبان
let resultItem = NSExtensionItem()
let resultData = translated.data(using: .utf8)!
let attachment = NSItemProvider(
    item: resultData,
    typeIdentifier: kUTTypePlainText as String
)
resultItem.attachments = [attachment]
extensionContext?.completeRequest(
    returningItems: [resultItem], completionHandler: nil
)

پردازش داده‌ها و بازگرداندن نتیجه

Action Extension می‌تواند در دو حالت کار کند: با UI و بدون UI. در حالت بدون UI، افزونه اقدام را کاملاً در پس‌زمینه انجام می‌دهد و بلافاصله پس از پردازش completeRequest را فراخوانی می‌کند. در حالت با UI، افزونه یک کنترلر نشان می‌دهد، کاربر اقدام را تأیید می‌کند و تنها پس از آن completeRequest نتیجه را ارسال می‌کند. انتخاب حالت به پیچیدگی اقدام و نیاز به ورودی کاربر بستگی دارد.

بارگیری داده از پیوست

متد loadItem(forTypeIdentifier:) به صورت ناهمگام کار می‌کند — داده‌ها می‌توانند بزرگ باشند (تصاویر، ویدئو). NSItemProvider بارگیری جریانی و ذخیره‌سازی موقت را مدیریت می‌کند. برای تصاویر از kUTTypeImage، برای فایل‌ها از kUTTypeFileURL استفاده کنید. مهم: loadItem ممکن است در رشته فرعی پس‌زمینه فراخوانی شود — UI را فقط از طریق DispatchQueue.main به‌روزرسانی کنید.

بازگرداندن داده‌های تغییر یافته

Action Extension داده‌های پردازش‌شده را از طریق completeRequest با آرایه‌ای از NSExtensionItem بازمی‌گرداند. هر عنصر با نوع داده خروجی مطابقت دارد. برنامه میزبان می‌تواند محتوای اصلی را با محتوای پردازش‌شده جایگزین کند — مثلاً تصویر اصلی را با تصویر فیلترشده جایگزین کند. NSExtensionItem از همان UTIهای ورودی به علاوه موارد اضافی (مانند public.html برای محتوای وب) پشتیبانی می‌کند.

سناریوهای استفاده از Action Extension

Action Extension در ده‌ها سناریو به کار می‌رود — از ابزارهای ساده تا فرآیندهای تجاری پیچیده. نمونه‌های کلاسیک عملیات متنی، گرافیکی و فایلی و همچنین یکپارچه‌سازی با محتوای وب را شامل می‌شوند.

سناریوهای متنی

Action Extension برای متن: ترجمه، بررسی املا، شمارش کاراکترها، تغییر حروف، رمزگذاری، ایجاد کد QR از متن. کاربر متن را در هر برنامه‌ای با فیلد متنی (Safari، یادداشت‌ها، ایمیل) انتخاب می‌کند و با یک کلیک اقدام را انجام می‌دهد. برجسته‌سازی نحوی کد، قالب‌بندی Markdown و کوتاه‌سازی URL — نمونه‌های محبوب Action Extension برای کاربران پیشرفته.

سناریوهای گرافیکی

برای تصاویر، Action Extension ارائه می‌دهد: اعمال فیلترها، برش، تغییر اندازه، تبدیل فرمت‌ها (HEIC به JPEG)، افزودن واترمارک، تشخیص متن (OCR) و فشرده‌سازی. پردازش تصاویر باید سریع باشد — کاربر در 2–3 ثانیه نتیجه را انتظار دارد. برای عملیات سنگین از Core Image روی GPU یا صف‌های پس‌زمینه استفاده کنید.

سناریوهای وب

Action Extension برای URL: ایجاد PDF از صفحه وب، ذخیره در Pocket/Pinterest، بررسی سرعت سایت، بایگانی صفحه، دریافت متاداده Open Graph، تولید اسکرین‌شات از صفحه. تولید PDF — یکی از محبوب‌ترین سناریوها: کاربر صفحه وب را بدون باز کردن سرویس‌های شخص ثالث به PDF تبدیل می‌کند.