WidgetKit — was ist das, Widget-Framework und SwiftUI

Was ist WidgetKit und wie funktioniert es?

WidgetKit ist ein Apple-Framework zum Erstellen von Widgets, die Inhalte auf den Systembildschirmen von Apple-Geräten anzeigen. Ein Widget ist eine Miniaturdarstellung Ihrer App, die der Benutzer im Jiggle-Modus auf dem Startbildschirm platziert. Im Gegensatz zu watchOS-Komplikationen, die es vor WidgetKit gab, hat das neue Framework die Widget-Erstellung für alle Apple-Plattformen über eine einheitliche SwiftUI-API vereinheitlicht.

Das Funktionsprinzip von WidgetKit basiert auf TimelineProvider — einem Objekt, das ein geordnetes Array von TimelineEntry erstellt, wobei jeder Eintrag einen Snapshot (einen bestimmten Widget-Zustand zu einem bestimmten Zeitpunkt) enthält. Das System zeigt die Einträge nacheinander an und aktualisiert das Widget beim Übergang zum nächsten Eintrag auf der Zeitachse. Zwischen den Einträgen ruft WidgetKit keinen App-Code auf — CPU-Zeit wird nur beim Erstellen einer neuen Timeline verbraucht.

Laut der WWDC 2024 Session „WidgetKit: What’s new“ hat der durchschnittliche iOS-Benutzer 8–12 Widgets auf dem Startbildschirm, wobei die beliebtesten Kategorien Wetter, Zeit, Kalender, Fitness und Finanzen sind. WidgetKit verbraucht bei typischer Nutzung weniger als 1% Akkuladung pro Tag, dank planmäßiger Aktualisierungen anstelle von Echtzeitaktualisierungen.

Was unterscheidet WidgetKit von alten Today Extensions

Vor iOS 14 existierten Widgets nur als Today View — ein Bedienfeld, das durch Wischen nach links vom ersten Bildschirm aus zugänglich war. Today Extensions hatten gravierende Einschränkungen: Sie waren nur auf dem „Today“-Bildschirm verfügbar, erforderten das Öffnen der App zur Aktualisierung des Inhalts und hatten eine begrenzte Größenunterstützung. WidgetKit hat Today Extensions vollständig ersetzt und bietet Widgets auf dem Startbildschirm, dem Sperrbildschirm (iOS 16+) und dem Mac-Desktop.

• Widgets auf dem Startbildschirm, nicht nur in Today View
• Autonome Aktualisierung über TimelineProvider, ohne Öffnen der App
• Drei vordefinierte Größen statt einer
• Smart Rotate und Smart Stack — automatische Widget-Rotation durch das System
• Einheitliche SwiftUI-API für alle Apple-Plattformen

WidgetKit-Architektur: TimelineProvider und Entry

Die WidgetKit-Architektur basiert auf drei Schlüsselprotokollen: TimelineProvider, TimelineEntry und Widget. TimelineEntry ist ein Datenmodell, das den Widget-Zustand zu einem bestimmten Zeitpunkt darstellt. TimelineProvider erstellt ein Array solcher Einträge (Timeline) und gibt das Aktivierungsdatum für jeden an. Widget ist der Einstiegspunkt, der den Anbieter mit der SwiftUI-Ansicht verbindet.

Die Timeline-Methode getTimeline wird vom System aufgerufen, wenn das Widget zum ersten Mal hinzugefügt wird, und dann periodisch — normalerweise alle 1–6 Stunden, abhängig vom Anbietertyp. Eine Timeline kann Einträge für Stunden oder Tage im Voraus enthalten, sodass das Widget ohne Aufruf von App-Code zwischen Aktualisierungen arbeiten kann. Wenn eine dringende Widget-Aktualisierung erforderlich ist (z. B. Wechselkursänderung), kann die App WidgetCenter.shared.reloadAllTimelines() erzwingen.

Basis-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 unterstützt drei Widget-Größen, jede mit festen Proportionen. Small (170×170 pt auf dem iPhone) zeigt kompakte Informationen an — einen einzelnen Wert, ein Symbol oder kurzen Text. Medium (364×170 pt) ist doppelt so breit wie small und eignet sich zur Anzeige von Wertepaaren oder Minidiagrammen. Large (364×382 pt) nimmt fast die Hälfte des Bildschirms vertikal ein und ermöglicht die Anzeige von Tabellen, Listen oder erweiterten Daten.

Der Entwickler muss mindestens zwei Größen unterstützen — Apple empfiehlt small + medium. Large Widget ist nur erforderlich, wenn die App genügend Inhalt hat, um dieses Volumen zu füllen. Jede Größe erhält ihre eigene SwiftUI View, die WidgetKit auf dem Systembildschirm rendert. Wichtig ist, dass WidgetKit keine benutzerdefinierten Größen unterstützt — nur drei feste Größen, was die Einheitlichkeit der Benutzeroberfläche gewährleistet.

Größenkonfiguration über 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])
    }
}

Widget-Konfigurationstypen: Static und Intent

WidgetKit bietet zwei Konfigurationstypen — StaticConfiguration und IntentConfiguration. StaticConfiguration eignet sich für Widgets, die allen Benutzern denselben Inhalt anzeigen: Wechselkurse, Wetter, Kalender. IntentConfiguration ermöglicht es dem Benutzer, das Widget beim Hinzufügen über das Siri-Intents-System anzupassen — beispielsweise eine bestimmte Stadt für das Wetter oder einen bestimmten Ticker für Aktienkurse auszuwählen.

IntentConfiguration verwendet INWidgetIntent — eine Unterklasse von INIntent aus SiriKit. Wenn der Benutzer ein Widget hinzufügt und Parameter auswählt (z. B. Stadt), speichert das System diesen Intent und übergibt ihn bei jeder Aktualisierung an TimelineProvider. Der Anbieter erhält den Intent in der getTimeline-Methode und verwendet seine Parameter zur Inhaltserstellung. IntentConfiguration ist der bevorzugte Ansatz für personalisierte Widgets, da es sich in Siri und Shortcuts integriert.

IntentConfiguration mit Parameterauswahl

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)
        }
    }
}

Erstellen eines Widgets in SwiftUI: Schritt-für-Schritt-Beispiel

Die Erstellung eines Widgets beginnt mit dem Hinzufügen eines Widget Extension Target in Xcode: File → New → Target → Widget Extension. Xcode generiert automatisch eine Struktur mit TimelineEntry, TimelineProvider und WidgetConfiguration. Der Entwickler muss nur die SwiftUI View zur Anzeige der Daten implementieren und den Anbieter für einen korrekten Aktualisierungszeitplan konfigurieren.

Nachfolgend ein vollständiges Beispiel eines einfachen Widgets zur Anzeige des aktuellen Bitcoin-Preises: Provider lädt den Kurs über URLSession und erstellt eine Timeline mit stündlichen Aktualisierungen. WidgetSwiftUIView zeigt den Kurs in großer Schrift und die letzte Aktualisierungszeit in kleiner Schrift an.

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+ Sperrbildschirm-Widgets

Mit iOS 16 hat WidgetKit die Unterstützung auf den Sperrbildschirm — den iPhone-Sperrbildschirm — erweitert. Sperrbildschirm-Widgets gibt es in zwei Ausführungen: inline (eine einzelne Textzeile unter der Uhr) und rectangular (ein rechteckiger Bereich). Im Gegensatz zu Startbildschirm-Widgets werden Sperrbildschirm-Widgets häufiger aktualisiert — der Systemauslöser ermöglicht Aktualisierungen alle 15–30 Minuten, um aktuelle Informationen anzuzeigen, ohne das Telefon zu entsperren.

Sperrbildschirm-Widgets erfordern eine separate Konfiguration über WidgetConfiguration mit accessoryFamilies: accessoryCircular, accessoryRectangular, accessoryInline. Diese Familien haben strenge Größen- und Inhaltsbeschränkungen — sie unterstützen keine Bilder, Animationen oder benutzerdefinierten Schriftarten. Apple empfiehlt, für Sperrbildschirm-Widgets nur Textinformationen und SF Symbols-Systemsymbole zu verwenden.

• accessoryCircular — kompaktes kreisförmiges Widget für den Bereich unter der Uhr
• accessoryRectangular — rechteckiges Widget für den Bereich über der Uhr
• accessoryInline — einzeiliger Text unter der Uhrzeit, Mindestgröße
• Einschränkungen: nur Text, SF Symbols, Farbverläufe; keine Bilder oder Videos

WidgetKit Best Practices und Einschränkungen

Bei der Entwicklung von Widgets ist es wichtig, die Einschränkungen von WidgetKit zu berücksichtigen. Widgets sind schreibgeschützte Ansichten: Sie verarbeiten keine Touch-Ereignisse (außer einem Tippen, das die App öffnet). Widgets unterstützen keine Animationen, Videos, Tastatureingaben, Scrollen oder interaktive Elemente. Jedes Widget ist ein statischer Daten-Snapshot zu einem bestimmten Zeitpunkt, und der Versuch, Interaktivität hinzuzufügen, führt zur Ablehnung der App im App Store.

Zu den Best Practices gehören die Verwendung von Widget Center für erzwungene Aktualisierungen, das Zwischenspeichern von Daten auf TimelineProvider-Ebene für schnelle Reaktionen und die Verwendung von Platzhaltern für den Anfangszustand. Wichtig ist auch die Unterstützung mehrerer Größen — Benutzer erwarten, dass das Widget sowohl in der small- als auch in der medium-Variante verfügbar ist. Vermeiden Sie strikt die Anzeige ungenauer oder veralteter Daten — Benutzer merken sich falsche Informationen aus Widgets lange.

WidgetKit-Einschränkungen Tabelle