AppIntent: ما هو، نموذج intents Siri وSwift

ما هو AppIntent ولماذا هو مطلوب؟

AppIntent هو إطار عمل من Apple لوصف الأوامر بشكل تصريحي التي يمكن لتطبيقك تنفيذها بناءً على طلب Siri وShortcuts وSpotlight وControl Center وAction Button. يعتمد على بروتوكول AppIntent، حيث يصف المطور اسم intent ومعلماته وطريقة perform() — المنطق القابل للتنفيذ. يقوم الإطار تلقائيًا بإنشاء واجهة مستخدم لتكوين المعلمات في تطبيق Shortcuts وعبارات صوتية لـ Siri.

قبل AppIntent، كان المطورون يستخدمون Intents framework — نظام يعتمد على ملف Intents Definition File الذي يولد كود Objective-C ويتطلب إعداد Intents Extension منفصل. كانت هذه العملية مرهقة: حتى intent بسيط كان يتطلب ما يصل إلى 5 ملفات تكوين. AppIntent يزيل هذا التعقيد — يتم وصف intent في ملف Swift واحد، ويقوم النظام تلقائيًا بإنشاء كل ما هو ضروري للتكامل مع Siri وShortcuts.

وفقًا لجلسة WWDC 2024 "Dive deeper into App Intents"، ترى Apple أن AppIntent هو الآلية المركزية لتوسيع وظائف التطبيقات خارج واجهة المستخدم التقليدية. بحلول وقت إصدار iOS 18، أكثر من 70% من التطبيقات في أفضل 100 من App Store تستخدم بالفعل AppIntent للتكامل مع Shortcuts وSiri، ويطلق مستخدم iOS 18 العادي 4-6 intents يوميًا عبر الأوامر الصوتية أو الأدوات.

أين يُستخدم AppIntent

• Siri — الأوامر الصوتية: "Hey Siri، أضف مهمة إلى MyApp"
• Shortcuts — الأتمتة في تطبيق الاختصارات مع تكوين المعلمات
• Spotlight — البحث وتنفيذ الأوامر مباشرة من شريط البحث
• Control Center — أزرار الإجراء السريع على iOS 18+
• Action Button — تعيين إجراء لزر iPhone 15 Pro والأحدث

AppIntent مقابل Intents framework: الاختلافات الرئيسية

Intents framework (iOS 10–15) كان يتطلب إنشاء ملف .intentdefinition، وتوليد فئات ObjC/Swift عبر Xcode، وإعداد Intents Extension وApp Intent Configuration. AppIntent (iOS 16+) يستبدل هذه العملية بالكامل بكود Swift نقي بدون توليد أو امتدادات أو تكوينات إضافية. وهذا يجعل عملية إنشاء intents في متناول مطور iOS العادي دون دراسة SiriKit.

الميزة الرئيسية لـ AppIntent هي التصريحية. يصف المطور ما يفعله intent، وليس كيفية تكامله مع النظام. يتولى الإطار نفسه معالجة سيناريوهات حوار Siri وعرض المعلمات في Shortcuts ونقل السياق بين intents. في Intents framework القديم، كان يجب ترميز كل جانب من جوانب التكامل يدويًا، بما في ذلك INUIHostedView لعرض واجهة مستخدم intent.

مقارنة النهج

البروتوكولات الرئيسية: AppIntent، AppEntity، AppEnum

AppIntent هو البروتوكول المركزي الذي يحدد intent. يحتوي على title (اسم لـ Siri)، وdescription (وصف في Shortcuts)، ومعلمات (عبر @Parameter) وطريقة perform() التي تعيد IntentResult. يمكن أن تكون النتيجة IntentDialog (حوار مع Siri)، أو قيمة للإرجاع إلى Shortcuts، أو خطأ. يمكن لكل intent أيضًا تقديم suggestedInvocationPhrase — عبارة للاستدعاء الصوتي.

AppEntity يصف الكيانات التي تعمل معها intents. على سبيل المثال، إذا كان التطبيق يدير المشاريع، فإن AppEntity Project يحتوي على id، وdisplayRepresentation (كيفية عرض الكيان في واجهة المستخدم) وdefaultQuery (كيفية البحث عن الكيانات). AppEnum هو تعداد لمعلمات الاختيار الذي يولد تلقائيًا واجهة مستخدم بعنصر منتقي في Shortcuts. بدلاً من إنشاء قائمة معلمات يدويًا، يكفي تعريف enum متوافق مع AppEnum.

مثال AppEnum ومعلمة

enum TaskPriority: String, AppEnum {
    case low, medium, high
    
    static var typeDisplayRepresentation: TypeDisplayRepresentation =
        "Priority"
    
    var displayRepresentation: DisplayRepresentation {
        switch self {
        case .low: "Low"
        case .medium: "Medium"
        case .high: "High"
        }
    }
}

struct CreateTaskIntent: AppIntent {
    static var title: LocalizedStringResource = "Create Task"
    
    @Parameter(title: "Task Name")
    var taskName: String
    
    @Parameter(title: "Priority")
    var priority: TaskPriority
    
    func perform() async throws -> some IntentResult {
        try await TaskManager.shared
            .createTask(name: taskName, priority: priority)
        return .result(dialog: "Task created")
    }
}

معلمات intents والتحقق من صحتها

يتم تعريف معلمات AppIntent من خلال property wrapper @Parameter، الذي يتكامل تلقائيًا مع واجهة مستخدم Shortcuts وطلبات Siri الصوتية. لكل معلمة title (يُعرض في Shortcuts) ويمكن أن تحتوي على وصف وقيم افتراضية وقيود. يدعم AppIntent الأنواع القياسية: String وInt وDouble وBool، بالإضافة إلى الأنواع المخصصة عبر AppEntity وAppEnum.

يتم التحقق من صحة المعلمات في طريقة perform() قبل تنفيذ المنطق. إذا كانت المعلمات غير صحيحة، يُرجع intent خطأ عبر IntentError. للتحقق المعقد، يمكن تنفيذ طريقة validate() التي تُستدعى قبل perform() ويمكنها تقديم تغذية راجعة للمستخدم عبر IntentDialog حتى قبل تنفيذ الأمر. هذا مفيد بشكل خاص لسيناريوهات Siri الصوتية، حيث إعادة سؤال المستخدم أسهل من تنفيذ أمر غير صحيح.

معلمات مع التحقق

struct SendMessageIntent: AppIntent {
    static var title: LocalizedStringResource = "Send Message"
    
    @Parameter(title: "Recipient")
    var recipient: String
    
    @Parameter(title: "Message")
    var message: String
    
    func validate() throws {
        guard message.count >= 1 else {
            throw IntentError.invalidMessage
        }
    }
    
    func perform() async throws -> some IntentResult {
        try await Messenger.shared
            .send(recipient: recipient, text: message)
        return .result(dialog: "Sent!")
    }
}

إنشاء intent في Swift: مثال

مثال كامل لintent للبحث عن الملاحظات في تطبيق يوضح العمل مع AppEntity وEntityQuery. يأخذ SearchNotesIntent سلسلة بحث ويعيد قائمة من الملاحظات التي تم العثور عليها. يصف AppEntity Note هيكل الملاحظة، وينفذ EntityQuery البحث عبر المخزن. يتم إرجاع النتيجة عبر IntentResult مع مصفوفة من الكيانات، والتي يعرضها Shortcuts للمستخدم.

struct Note: AppEntity {
    let id: UUID
    let title: String
    let content: String
    
    static var typeDisplayRepresentation: TypeDisplayRepresentation =
        "Note"
    
    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "(title)")
    }
}

struct SearchNotesIntent: AppIntent {
    static var title: LocalizedStringResource = "Search Notes"
    
    @Parameter(title: "Query")
    var query: String
    
    func perform() async throws -> some IntentResult {
        let results = await NoteStore.shared
            .search(query)
            .map { $0.toEntity() }
        return .result(value: results)
    }
}

التكامل مع Shortcuts وSiri

بعد تعريف AppIntent، يحدث التكامل مع Shortcuts وSiri تلقائيًا. يقوم تطبيق Shortcuts بمسح جميع AppIntents من التطبيقات المثبتة ويعرضها في قائمة الإجراءات المتاحة. يمكن للمستخدم إضافة intent إلى اختصاره، وتكوين معلماته ودمجه مع إجراءات أخرى. بالنسبة لـ Siri، تظهر intents كأوامر صوتية بدون إعداد إضافي من المطور.

يمكن للمطور تحسين التكامل بإضافة suggestedInvocationPhrase — عبارة موصى بها للاستدعاء الصوتي. على سبيل المثال، لintent إضافة مهمة: suggestedInvocationPhrase = "Add new task". تحلل Siri هذه العبارة وتقترحها على المستخدم عند تعلم الأوامر الصوتية. يمكن أيضًا تحديد categories — فئة intent (create، view، search، edit)، مما يساعد Shortcuts في تجميع الإجراءات حسب المعنى.

فئات intents لـ Shortcuts