WidgetKit — τι είναι, framework widgets και SwiftUI

Τι είναι το WidgetKit και πώς λειτουργεί;

WidgetKit — το framework της Apple για τη δημιουργία widgets που εμφανίζουν περιεχόμενο στις οθόνες συστήματος των συσκευών Apple. Ένα widget είναι μια μικρογραφία της εφαρμογής σας που ο χρήστης τοποθετεί στην αρχική οθόνη σε λειτουργία „κουνήματος” (jiggle mode). Σε αντίθεση με τις watchOS complications που υπήρχαν πριν από το WidgetKit, το νέο framework ενοποίησε τη δημιουργία widgets για όλες τις πλατφόρμες Apple μέσω ενός ενιαίου API στο SwiftUI.

Η αρχή λειτουργίας του WidgetKit βασίζεται στο TimelineProvider — ένα αντικείμενο που δημιουργεί μια ταξινομημένη συστοιχία TimelineEntry, όπου κάθε εγγραφή περιέχει ένα Snapshot (τη συγκεκριμένη κατάσταση του widget σε μια δεδομένη χρονική στιγμή). Το σύστημα εμφανίζει τις εγγραφές διαδοχικά, ενημερώνοντας το widget κατά τη μετάβαση στην επόμενη εγγραφή στη χρονογραμμή. Μεταξύ των εγγραφών, το WidgetKit δεν καλεί τον κώδικα της εφαρμογής — ο χρόνος επεξεργαστή δαπανάται μόνο κατά τη δημιουργία ενός νέου Timeline.

Σύμφωνα με τα δεδομένα του WWDC 2024 Session „WidgetKit: What’s new”, ο μέσος χρήστης iOS έχει 8–12 widgets στην αρχική οθόνη και οι πιο δημοφιλείς κατηγορίες είναι καιρός, ώρα, ημερολόγιο, γυμναστική και οικονομικά. Το WidgetKit καταναλώνει λιγότερο από 1% μπαταρία την ημέρα σε τυπική χρήση, επειδή οι ενημερώσεις γίνονται βάσει προγράμματος, όχι σε πραγματικό χρόνο.

Τι διαφοροποιεί το WidgetKit από τα παλιά Today Extension

Πριν από το iOS 14, τα widgets υπήρχαν μόνο ως Today View — ένα πάνελ προσβάσιμο με σάρωση προς τα αριστερά από την πρώτη οθόνη. Τα Today Extension είχαν σοβαρούς περιορισμούς: ήταν διαθέσιμα μόνο στην οθόνη „Σήμερα”, απαιτούσαν το άνοιγμα της εφαρμογής για την ενημέρωση περιεχομένου και είχαν περιορισμένη υποστήριξη μεγεθών. Το WidgetKit αντικατέστησε πλήρως τα Today Extension, παρέχοντας widgets στην αρχική οθόνη, στην οθόνη κλειδώματος (iOS 16+) και στην επιφάνεια εργασίας Mac.

• Widgets στην αρχική οθόνη, όχι μόνο στο Today View
• Αυτόνομη ενημέρωση μέσω TimelineProvider, χωρίς άνοιγμα της εφαρμογής
• Τρία προκαθορισμένα μεγέθη αντί για ένα
• Smart Rotate και Smart Stack — αυτόματη εναλλαγή widgets από το σύστημα
• Ενιαίο API στο SwiftUI για όλες τις πλατφόρμες Apple

Αρχιτεκτονική WidgetKit: TimelineProvider και Entry

Η αρχιτεκτονική του WidgetKit βασίζεται σε τρία βασικά πρωτόκολλα: TimelineProvider, TimelineEntry και Widget. Το TimelineEntry είναι ένα μοντέλο δεδομένων που αντιπροσωπεύει την κατάσταση του widget σε μια συγκεκριμένη χρονική στιγμή. Το TimelineProvider δημιουργεί μια συστοιχία τέτοιων εγγραφών (Timeline), καθορίζοντας την ημερομηνία ενεργοποίησης για καθεμία. Widget — το σημείο εισόδου που συνδέει τον πάροχο με την προβολή SwiftUI.

Η μέθοδος getTimeline καλείται από το σύστημα κατά την πρώτη προσθήκη του widget και στη συνέχεια περιοδικά — συνήθως κάθε 1–6 ώρες ανάλογα με τον τύπο παρόχου. Το Timeline μπορεί να περιέχει εγγραφές για ώρες ή ημέρες μπροστά, επιτρέποντας στο widget να λειτουργεί χωρίς να καλεί τον κώδικα της εφαρμογής μεταξύ των ενημερώσεων. Εάν το widget χρειάζεται επείγουσα ενημέρωση (π.χ., άλλαξε η ισοτιμία), η εφαρμογή μπορεί να καλέσει το 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 υποστηρίζει τρία μεγέθη widgets, το καθένα με σταθερές αναλογίες. Το Small (170×170 pt στο iPhone) εμφανίζει συμπαγείς πληροφορίες — μια τιμή, εικονίδιο ή σύντομο κείμενο. Το Medium (364×170 pt) είναι διπλάσιο σε πλάτος από το small και κατάλληλο για την εμφάνιση μερικών τιμών ή μίνι γραφήματος. Το Large (364×382 pt) καταλαμβάνει σχεδόν το μισό της οθόνης κάθετα και επιτρέπει την εμφάνιση πινάκων, λιστών ή εκτεταμένων δεδομένων.

Ο προγραμματιστής πρέπει να υποστηρίζει τουλάχιστον δύο μεγέθη — η Apple συνιστά small + medium. Το Large widget απαιτείται μόνο εάν η εφαρμογή έχει αρκετό περιεχόμενο για να γεμίσει έναν τέτοιο όγκο. Κάθε μέγεθος λαμβάνει τη δική του προβολή 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])
    }
}

Τύποι διαμόρφωσης widgets: Static και Intent

Το WidgetKit προσφέρει δύο τύπους διαμόρφωσης — StaticConfiguration και IntentConfiguration. Το StaticConfiguration είναι κατάλληλο για widgets που εμφανίζουν το ίδιο περιεχόμενο για όλους τους χρήστες: ισοτιμίες, καιρός, ημερολόγιο. Το IntentConfiguration επιτρέπει στο χρήστη να προσαρμόσει το widget κατά την προσθήκη μέσω του συστήματος intent του Siri — για παράδειγμα, να επιλέξει μια συγκεκριμένη πόλη για τον καιρό ή ένα συγκεκριμένο ticker για την τιμή της μετοχής.

Το IntentConfiguration χρησιμοποιεί INWidgetIntent — μια υποκλάση του INIntent από το SiriKit. Όταν ο χρήστης προσθέτει ένα widget και επιλέγει παραμέτρους (π.χ., πόλη), το σύστημα αποθηκεύει αυτό το intent και το μεταβιβάζει στο TimelineProvider σε κάθε ενημέρωση. Ο πάροχος λαμβάνει το intent στη μέθοδο getTimeline και χρησιμοποιεί τις παραμέτρους του για να δημιουργήσει περιεχόμενο. Το IntentConfiguration είναι η προτιμώμενη μέθοδος για εξατομικευμένα widgets, καθώς ενσωματώνεται με το 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)
        }
    }
}

Δημιουργία widget στο SwiftUI: παράδειγμα βήμα προς βήμα

Η δημιουργία ενός widget ξεκινά με την προσθήκη Widget Extension Target στο Xcode: File → New → Target → Widget Extension. Το Xcode δημιουργεί αυτόματα μια δομή με TimelineEntry, TimelineProvider και WidgetConfiguration. Στον προγραμματιστή απομένει μόνο να υλοποιήσει την προβολή SwiftUI για την εμφάνιση δεδομένων και να ρυθμίσει τον πάροχο για σωστό πρόγραμμα ενημερώσεων.

Παρακάτω — ένα πλήρες παράδειγμα ενός απλού widget για την εμφάνιση της τρέχουσας τιμής του 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 ? "+" : "")
        }
    }
}

Widgets οθόνης κλειδώματος iOS 16+

Από το iOS 16, το WidgetKit επέκτεινε την υποστήριξη στο Lock Screen — την οθόνη κλειδώματος του iPhone. Τα Lock Screen widgets είναι δύο τύπων: inline (μία γραμμή κειμένου κάτω από το ρολόι) και rectangular (ορθογώνια περιοχή). Σε αντίθεση με τα Home Screen widgets, τα Lock Screen widgets ενημερώνονται συχνότερα — η σκανδάλη συστήματος επιτρέπει την ενημέρωσή τους κάθε 15–30 λεπτά για την εμφάνιση επικαιροποιημένων πληροφοριών χωρίς ξεκλείδωμα του τηλεφώνου.

Τα Lock Screen widgets απαιτούν ξεχωριστή διαμόρφωση μέσω WidgetConfiguration με accessoryFamilies: accessoryCircular, accessoryRectangular, accessoryInline. Αυτές οι οικογένειες έχουν αυστηρούς περιορισμούς μεγέθους και περιεχομένου — δεν υποστηρίζουν εικόνες, κινούμενα σχέδια και προσαρμοσμένες γραμματοσειρές. Η Apple συνιστά τη χρήση μόνο πληροφοριών κειμένου και εικονιδίων συστήματος SF Symbols για τα Lock Screen widgets.

• accessoryCircular — συμπαγές κυκλικό widget για τη θέση κάτω από το ρολόι
• accessoryRectangular — ορθογώνιο widget για την περιοχή πάνω από το ρολόι
• accessoryInline — μονόγραμμο κείμενο κάτω από την ώρα, ελάχιστο μέγεθος
• Περιορισμοί: μόνο κείμενο, SF Symbols, διαβαθμίσεις; χωρίς εικόνες και βίντεο

Βέλτιστες πρακτικές και περιορισμοί WidgetKit

Κατά την ανάπτυξη widgets είναι σημαντικό να λαμβάνονται υπόψη οι περιορισμοί του WidgetKit. Τα widgets είναι προβολές μόνο για ανάγνωση: δεν επεξεργάζονται γεγονότα αφής (εκτός από το πάτημα που ανοίγει την εφαρμογή). Τα widgets δεν υποστηρίζουν κινούμενα σχέδια, βίντεο, είσοδο πληκτρολογίου, κύλιση ή διαδραστικά στοιχεία. Κάθε widget είναι ένα στατικό στιγμιότυπο δεδομένων σε μια δεδομένη χρονική στιγμή και η προσθήκη διαδραστικότητας θα οδηγήσει στην απόρριψη της εφαρμογής στο App Store.

Οι βέλτιστες πρακτικές περιλαμβάνουν το Widget Center για αναγκαστική ενημέρωση, προσωρινή αποθήκευση δεδομένων στο επίπεδο του TimelineProvider για γρήγορη απόκριση και χρήση placeholder για την αρχική κατάσταση. Επίσης σημαντική είναι η υποστήριξη πολλαπλών μεγεθών — ο χρήστης αναμένει ότι το widget θα είναι διαθέσιμο τόσο σε small όσο και σε medium έκδοση. Αποφύγετε την εμφάνιση ανακριβών ή ξεπερασμένων δεδομένων — ο χρήστης θυμάται λανθασμένες πληροφορίες από το widget για μεγάλο χρονικό διάστημα.

Περιορισμοί WidgetKit σε πίνακα