WidgetKit — ما هو، إطار عمل الأدوات وSwiftUI

ما هو WidgetKit وكيف يعمل؟

WidgetKit هو إطار عمل من Apple لإنشاء أدوات تعرض المحتوى على شاشات النظام لأجهزة Apple. الأداة هي تمثيل مصغر لتطبيقك يقوم المستخدم بوضعه على الشاشة الرئيسية في وضع jiggle. على عكس تعقيدات watchOS التي كانت موجودة قبل WidgetKit، وحدّ الإطار الجديد إنشاء الأدوات لجميع منصات Apple من خلال واجهة برمجة تطبيقات موحدة على SwiftUI.

يعتمد مبدأ عمل WidgetKit على TimelineProvider — كائن ينشئ مصفوفة مرتبة من TimelineEntry، حيث يحتوي كل إدخال على Snapshot (حالة محددة للتطبيق الصغير في وقت معين). يعرض النظام الإدخالات بالتسلسل، مع تحديث التطبيق الصغير عند الانتقال إلى الإدخال التالي على الخط الزمني. بين الإدخالات، لا يستدعي WidgetKit كود التطبيق — يتم استهلاك وقت المعالج فقط عند إنشاء Timeline جديد.

وفقًا لجلسة WWDC 2024 «WidgetKit: What’s new»، يمتلك المستخدم العادي لنظام iOS من 8 إلى 12 أداة على شاشته الرئيسية، وأكثر الفئات شيوعًا هي الطقس والوقت والتقويم واللياقة البدنية والمالية. يستهلك WidgetKit أقل من 1% من شحن البطارية يوميًا مع الاستخدام النموذجي، وذلك بفضل التحديثات المجدولة بدلاً من التحديثات في الوقت الفعلي.

ما الذي يميز WidgetKit عن Today Extensions القديمة

قبل iOS 14، كانت الأدوات موجودة فقط كـ Today View — لوحة يمكن الوصول إليها عن طريق التمرير لليسار من الشاشة الأولى. كانت Today Extensions ذات قيود خطيرة: كانت متاحة فقط على شاشة «اليوم»، وتطلبت فتح التطبيق لتحديث المحتوى، وكان دعم الأحجام محدودًا. WidgetKit استبدل Today Extensions بالكامل، حيث وفر أدوات على الشاشة الرئيسية وشاشة القفل (iOS 16+) وسطح مكتب Mac.

• أدوات على الشاشة الرئيسية، وليس فقط في Today View
• تحديث مستقل عبر TimelineProvider، دون فتح التطبيق
• ثلاثة أحجام محددة مسبقًا بدلاً من واحد
• Smart Rotate وSmart Stack — التدوير التلقائي للأدوات بواسطة النظام
• واجهة برمجة تطبيقات موحدة على SwiftUI لجميع منصات Apple

هندسة WidgetKit: TimelineProvider وEntry

تعتمد هندسة WidgetKit على ثلاثة بروتوكولات رئيسية: TimelineProvider وTimelineEntry وWidget. TimelineEntry هو نموذج بيانات يمثل حالة التطبيق الصغير في وقت محدد. TimelineProvider ينشئ مصفوفة من هذه الإدخالات (Timeline)، مع تحديد تاريخ التفعيل لكل منها. Widget هو نقطة الدخول التي تربط المزوّد بعرض SwiftUI.

طريقة Timeline getTimeline يتم استدعاؤها بواسطة النظام عند إضافة التطبيق الصغير لأول مرة، ثم بشكل دوري — عادة كل 1–6 ساعات اعتمادًا على نوع المزوّد. يمكن أن يحتوي Timeline على إدخالات لساعات أو أيام مقدمًا، مما يسمح للتطبيق الصغير بالعمل دون استدعاء كود التطبيق بين التحديثات. إذا كانت هناك حاجة لتحديث عاجل (على سبيل المثال، تغير سعر العملة)، يمكن للتطبيق استدعاء WidgetCenter.shared.reloadAllTimelines() قسرًا.

TimelineProvider الأساسي

struct SimpleEntry: TimelineEntry {
    let date: Date
    let value: Double
}

struct Provider: TimelineProvider {
    typealias Entry = SimpleEntry
    
    func placeholder(in context: Context) -> Entry {
        Entry(date: Date(), value: 0)
    }
    
    func getSnapshot(
        in context: Context,
        completion: @escaping (Entry) -> Void
    ) {
        Entry(date: Date(), value: 42.5)
    }
    
    func getTimeline(
        in context: Context,
        completion: @escaping (Timeline<Entry>, Error?) -> Void
    ) {
        let entry = Entry(date: Date(), value: fetchLatestValue())
        let nextUpdate = Calendar.current
            .date(byAdding: .hour, value: 1, to: Date())!
        let timeline = Timeline(entries: [entry], policy: .after(nextUpdate))
        completion(timeline, nil)
    }
}

Widget Family: small, medium, large

يدعم WidgetKit ثلاثة أحجام للأدوات، لكل منها نسب ثابتة. Small (170×170 نقطة على iPhone) يعرض معلومات مضغوطة — قيمة واحدة أو أيقونة أو نص قصير. Medium (364×170 نقطة) أعرض بمرتين من small ومناسب لعرض زوج من القيم أو رسم بياني مصغر. Large (364×382 نقطة) يشغل نصف الشاشة تقريبًا رأسيًا ويسمح بعرض الجداول أو القوائم أو البيانات الموسعة.

يجب على المطور دعم حجمين على الأقل — توصي Apple بـ small + medium. الأداة Large مطلوبة فقط إذا كان التطبيق يحتوي على محتوى كافٍ لملء هذا الحجم. يحصل كل حجم على عرض SwiftUI الخاص به، والذي يقوم WidgetKit بعرضه على شاشة النظام. من المهم أن WidgetKit لا يدعم الأحجام المخصصة — فقط ثلاثة أحجام ثابتة، مما يضمن اتساق الواجهة.

تهيئة الأحجام عبر WidgetConfiguration

struct WeatherWidget: Widget {
    let kind: String = "WeatherWidget"
    
    var body: some WidgetConfiguration {
        StaticConfiguration(kind: kind, provider: Provider()) { entry in
            WeatherWidgetView(entry: entry)
        }
        .configurationDisplayName("Weather")
        .description("Current temperature and forecast")
        .supportedFamilies([.systemSmall, .systemMedium])
    }
}

أنواع تهيئة الأدوات: Static وIntent

يقدم WidgetKit نوعين من التهيئة — StaticConfiguration وIntentConfiguration. StaticConfiguration مناسب للأدوات التي تعرض نفس المحتوى لجميع المستخدمين: أسعار العملات والطقس والتقويم. IntentConfiguration يسمح للمستخدم بتخصيص الأداة عند إضافتها من خلال نظام intents في Siri — على سبيل المثال، اختيار مدينة معينة للطقس أو مؤشر معين لأسعار الأسهم.

يستخدم IntentConfiguration INWidgetIntent — فئة فرعية من INIntent من SiriKit. عندما يضيف المستخدم أداة ويختار معايير (مثل المدينة)، يحفظ النظام هذا intent ويمرره إلى TimelineProvider في كل تحديث. يستلم المزوّد intent في طريقة getTimeline ويستخدم معاييره لتكوين المحتوى. IntentConfiguration هو الأسلوب المفضل للأدوات المخصصة، حيث يتكامل مع Siri وShortcuts.

IntentConfiguration مع اختيار المعايير

struct WeatherWidgetEntryView: View {
    var entry: WeatherEntry
    
    var body: some View {
        VStack(alignment: .leading) {
            Text(entry.cityName)
                .font(.caption)
                .foregroundColor(.secondary)
            Text("\(entry.temperature)°C")
                .font(.largeTitle)
        }
    }
}

struct WeatherWidget: Widget {
    var body: some WidgetConfiguration {
        IntentConfiguration(
            kind: "WeatherWidget",
            intent: WeatherConfigIntent.self,
            provider: WeatherTimelineProvider()
        ) { entry in
            WeatherWidgetEntryView(entry: entry)
        }
    }
}

إنشاء أداة في SwiftUI: مثال خطوة بخطوة

يبدأ إنشاء أداة بإضافة Widget Extension Target في Xcode: File ← New ← Target ← Widget Extension. يقوم Xcode تلقائيًا بإنشاء هيكل مع TimelineEntry وTimelineProvider وWidgetConfiguration. يتبقى على المطور فقط تنفيذ عرض SwiftUI لعرض البيانات وتهيئة المزوّد لجدول تحديث صحيح.

أدناه مثال كامل لأداة بسيطة لعرض سعر Bitcoin الحالي: Provider يقوم بتحميل السعر عبر URLSession وينشئ Timeline مع تحديثات كل ساعة. يعرض WidgetSwiftUIView السعر بخط كبير ووقت آخر تحديث بخط صغير.

struct BTCPriceEntry: TimelineEntry {
    let date: Date
    let price: Double
    let change24h: Double
}

struct BTCWidgetEntryView: View {
    var entry: BTCPriceEntry
    
    var body: some View {
        VStack {
            Text("BTC/USD").font(.caption)
            Text("$\(entry.price, specifier: "%.0f")")
                .font(.title2).fontWeight(.bold)
            Text(entry.change24h > 0 ? "+" : "")
        }
    }
}

أدوات شاشة القفل iOS 16+

مع iOS 16، وسّع WidgetKit الدعم ليشمل شاشة القفل — شاشة قفل iPhone. أدوات شاشة القفل من نوعين: inline (سطر واحد من النص أسفل الساعة) وrectangular (منطقة مستطيلة). على عكس أدوات الشاشة الرئيسية، يتم تحديث أدوات شاشة القفل بشكل متكرر — يسمح مشغل النظام بتحديثها كل 15–30 دقيقة لعرض المعلومات الحالية دون فتح القفل.

تتطلب أدوات شاشة القفل تهيئة منفصلة عبر WidgetConfiguration مع accessoryFamilies: accessoryCircular وaccessoryRectangular وaccessoryInline. هذه العائلات لها قيود صارمة على الحجم والمحتوى — لا تدعم الصور أو الرسوم المتحركة أو الخطوط المخصصة. توصي Apple باستخدام المعلومات النصية فقط وأيقونات النظام SF Symbols لأدوات شاشة القفل.

• accessoryCircular — أداة دائرية مضغوطة للمساحة أسفل الساعة
• accessoryRectangular — أداة مستطيلة للمساحة فوق الساعة
• accessoryInline — نص من سطر واحد أسفل الوقت، حجم أدنى
• القيود: نص فقط، SF Symbols، تدرجات؛ بدون صور أو فيديو

أفضل الممارسات والقيود في WidgetKit

عند تطوير الأدوات، من المهم مراعاة قيود WidgetKit. الأدوات هي عروض للقراءة فقط: لا تعالج أحداث اللمس (باستثناء النقرة التي تفتح التطبيق). لا تدعم الأدوات الرسوم المتحركة أو الفيديو أو إدخال لوحة المفاتيح أو التمرير أو العناصر التفاعلية. كل أداة هي لقطة ثابتة للبيانات في وقت معين، وأي محاولة لإضافة تفاعل ستؤدي إلى رفض التطبيق من App Store.

تشمل أفضل الممارسات استخدام Widget Center للتحديثات القسرية، وتخزين البيانات مؤقتًا على مستوى TimelineProvider للاستجابة السريعة، واستخدام placeholders للحالة الأولية. من المهم أيضًا دعم أحجام متعددة — يتوقع المستخدم أن تكون الأداة متاحة في كل من الإصدارين small وmedium. تجنب عرض بيانات غير دقيقة أو قديمة — يتذكر المستخدم المعلومات الخاطئة من الأدوات لفترة طويلة.

جدول قيود WidgetKit