WidgetKit — یہ کیا ہے، ویجٹ فریم ورک اور SwiftUI

WidgetKit کیا ہے اور یہ کیسے کام کرتا ہے؟

WidgetKit Apple آلات کی سسٹم اسکرینوں پر مواد ظاہر کرنے والے ویجٹ بنانے کے لیے ایک Apple فریم ورک ہے۔ ویجٹ آپ کی ایپ کی ایک چھوٹی نمائندگی ہے جسے صارف jiggle موڈ میں ہوم اسکرین پر رکھتا ہے۔ WidgetKit سے پہلے موجود watchOS Complications کے برعکس، نئے فریم ورک نے ایک واحد SwiftUI API کے ذریعے تمام Apple پلیٹ فارمز کے لیے ویجٹ بنانے کو یکجا کر دیا۔

WidgetKit کے کام کرنے کا اصول TimelineProvider پر مبنی ہے — ایک آبجیکٹ جو TimelineEntry کی ایک ترتیب شدہ صف بناتا ہے، جہاں ہر اندراج میں ایک Snapshot (ایک مخصوص وقت پر ویجٹ کی مخصوص حالت) ہوتی ہے۔ سسٹم اندراجات کو ترتیب وار ظاہر کرتا ہے، ٹائم لائن پر اگلے اندراج پر جانے پر ویجٹ کو اپ ڈیٹ کرتا ہے۔ اندراجات کے درمیان، WidgetKit ایپ کوڈ کو کال نہیں کرتا — CPU وقت صرف نیا 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 — سسٹم کے ذریعے خودکار ویجٹ گردش
• تمام Apple پلیٹ فارمز کے لیے یکجا SwiftUI API

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 (iPhone پر 170×170 pt) کمپیکٹ معلومات ظاہر کرتا ہے — ایک قدر، آئیکن یا مختصر متن۔ Medium (364×170 pt) small سے دوگنا چوڑا ہے اور قدروں کے جوڑے یا منی چارٹ ظاہر کرنے کے لیے موزوں ہے۔ Large (364×382 pt) عمودی طور پر تقریباً آدھی اسکرین لیتا ہے اور جدولوں، فہرستوں یا توسیعی ڈیٹا کو ظاہر کرنے کی اجازت دیتا ہے۔

ڈیولپر کو کم از کم دو سائز سپورٹ کرنے چاہئیں — Apple small + medium کی سفارش کرتا ہے۔ Large ویجٹ صرف اس صورت میں ضروری ہے جب ایپ میں اس حجم کو بھرنے کے لیے کافی مواد ہو۔ ہر سائز اپنا SwiftUI View حاصل کرتا ہے، جسے 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 صارف کو Siri انٹینٹ سسٹم کے ذریعے ویجٹ شامل کرتے وقت اسے اپنی مرضی کے مطابق بنانے کی اجازت دیتا ہے — مثال کے طور پر، موسم کے لیے کوئی مخصوص شہر یا اسٹاک قیمت کے لیے کوئی مخصوص ٹکر منتخب کرنا۔

IntentConfiguration INWidgetIntent استعمال کرتا ہے — SiriKit سے INIntent کا ایک ذیلی طبقہ۔ جب صارف ویجٹ شامل کرتا ہے اور پیرامیٹرز منتخب کرتا ہے (مثال کے طور پر، شہر)، سسٹم اس انٹینٹ کو محفوظ کرتا ہے اور ہر اپ ڈیٹ پر اسے TimelineProvider کو بھیجتا ہے۔ فراہم کنندہ 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 میں ویجٹ بنانا: مرحلہ وار مثال

ویجٹ بنانا Xcode میں Widget Extension Target شامل کرنے سے شروع ہوتا ہے: File → New → Target → Widget Extension۔ Xcode خود بخود TimelineEntry، TimelineProvider اور WidgetConfiguration کے ساتھ ایک ڈھانچہ تیار کرتا ہے۔ ڈیولپر کو صرف ڈیٹا ظاہر کرنے کے لیے SwiftUI View نافذ کرنا اور درست اپ ڈیٹ شیڈول کے لیے فراہم کنندہ کو کنفیگر کرنا ہوتا ہے۔

ذیل میں موجودہ 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 منٹ میں اپ ڈیٹ کی اجازت دیتا ہے۔

لاک اسکرین ویجٹ کو accessoryFamilies کے ساتھ WidgetConfiguration کے ذریعے علیحدہ کنفیگریشن کی ضرورت ہوتی ہے: accessoryCircular، accessoryRectangular، accessoryInline۔ ان خاندانوں میں سائز اور مواد کی سخت حدود ہیں — وہ تصاویر، اینیمیشن یا اپنی مرضی کے فونٹ کو سپورٹ نہیں کرتے۔ Apple لاک اسکرین ویجٹ کے لیے صرف متنی معلومات اور SF Symbols سسٹم آئیکن استعمال کرنے کی سفارش کرتا ہے۔

• accessoryCircular — گھڑی کے نیچے والے علاقے کے لیے کمپیکٹ سرکلر ویجٹ
• accessoryRectangular — گھڑی کے اوپر والے علاقے کے لیے مستطیل ویجٹ
• accessoryInline — وقت کے نیچے ایک لائن کا متن، کم سے کم سائز
• حدود: صرف متن، SF Symbols، گریڈینٹ؛ کوئی تصویر یا ویڈیو نہیں

WidgetKit بہترین طریقہ کار اور حدود

ویجٹ تیار کرتے وقت، WidgetKit کی حدود پر غور کرنا ضروری ہے۔ ویجٹ صرف پڑھنے کے لیے ویوز ہیں: وہ ٹچ ایونٹس کو ہینڈل نہیں کرتے (سوائے اس ٹیپ کے جو ایپ کھولتا ہے)۔ ویجٹ اینیمیشن، ویڈیو، کی بورڈ ان پٹ، اسکرولنگ یا انٹرایکٹو عناصر کو سپورٹ نہیں کرتے۔ ہر ویجٹ ایک مخصوص وقت پر ڈیٹا کا ایک جامد سنیپ شاٹ ہے، اور انٹرایکٹیویٹی شامل کرنے کی کوشش کے نتیجے میں ایپ کو App Store سے مسترد کر دیا جائے گا۔

بہترین طریقہ کار میں زبردستی اپ ڈیٹس کے لیے Widget Center کا استعمال، فوری ردعمل کے لیے TimelineProvider کی سطح پر ڈیٹا کیشنگ، اور ابتدائی حالت کے لیے placeholder کا استعمال شامل ہے۔ متعدد سائز کو سپورٹ کرنا بھی ضروری ہے — صارفین توقع کرتے ہیں کہ ویجٹ small اور medium دونوں شکلوں میں دستیاب ہو۔ غلط یا پرانے ڈیٹا کو ظاہر کرنے سے سختی سے گریز کریں — صارفین ویجٹ سے غلط معلومات کو طویل عرصے تک یاد رکھتے ہیں۔

WidgetKit حدود کا جدول