WidgetKit — wat is het, framework voor widgets en SwiftUI

Wat is WidgetKit en hoe werkt het?

WidgetKit — het Apple-framework voor het maken van widgets die inhoud weergeven op de systeemschermen van Apple-apparaten. Een widget is een miniatuurweergave van uw app die de gebruiker op het startscherm plaatst in de schudmodus (jiggle mode). In tegenstelling tot watchOS-complicaties die vóór WidgetKit bestonden, heeft het nieuwe framework het maken van widgets voor alle Apple-platforms via een uniforme API op SwiftUI gestroomlijnd.

Het werkingsprincipe van WidgetKit is gebaseerd op TimelineProvider — een object dat een geordende array van TimelineEntry maakt, waarbij elke entry een Snapshot (specifieke widgetstatus op een bepaald moment) bevat. Het systeem toont de entries sequentieel en werkt de widget bij bij de overgang naar de volgende entry op de tijdlijn. Tussen entries door roept WidgetKit geen app-code aan — processortijd wordt alleen verbruikt bij het maken van een nieuwe Timeline.

Volgens gegevens van WWDC 2024 Session „WidgetKit: What’s new” heeft de gemiddelde iOS-gebruiker 8–12 widgets op het startscherm, en de populairste categorieën zijn weer, tijd, agenda, fitness en financiën. WidgetKit verbruikt minder dan 1% batterij per dag bij normaal gebruik, omdat updates volgens een schema plaatsvinden, niet in realtime.

Wat onderscheidt WidgetKit van oude Today Extensions

Vóór iOS 14 bestonden widgets alleen als Today View — een paneel dat toegankelijk was door naar links te vegen vanaf het eerste scherm. Today Extensions hadden ernstige beperkingen: ze waren alleen beschikbaar op het „Vandaag”-scherm, vereisten het openen van de app voor het bijwerken van de inhoud en hadden beperkte ondersteuning voor formaten. WidgetKit heeft Today Extensions volledig vervangen door widgets aan te bieden op het startscherm, het vergrendelscherm (iOS 16+) en het Mac-bureaublad.

• Widgets op het startscherm, niet alleen in Today View
• Autonome updates via TimelineProvider, zonder de app te openen
• Drie vooraf gedefinieerde formaten in plaats van één
• Smart Rotate en Smart Stack — automatische rotatie van widgets door het systeem
• Uniforme API op SwiftUI voor alle Apple-platforms

WidgetKit-architectuur: TimelineProvider en Entry

De architectuur van WidgetKit is gebaseerd op drie belangrijke protocollen: TimelineProvider, TimelineEntry en Widget. TimelineEntry is een gegevensmodel dat de status van de widget op een specifiek moment vertegenwoordigt. TimelineProvider maakt een array van dergelijke entries (Timeline) met een activatiedatum voor elke entry. Widget — het toegangspunt dat de provider verbindt met de SwiftUI-weergave.

De methode getTimeline wordt door het systeem aangeroepen bij de eerste toevoeging van de widget en vervolgens periodiek — meestal elke 1–6 uur, afhankelijk van het providertype. Een Timeline kan entries voor uren of dagen vooruit bevatten, waardoor de widget kan werken zonder app-code aan te roepen tussen updates. Als de widget dringend moet worden bijgewerkt (bijvoorbeeld bij een gewijzigde wisselkoers), kan de app WidgetCenter.shared.reloadAllTimelines() geforceerd aanroepen.

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 ondersteunt drie widgetformaten, elk met vaste verhoudingen. Small (170×170 pt op iPhone) toont compacte informatie — een enkele waarde, pictogram of korte tekst. Medium (364×170 pt) is tweemaal zo breed als small en geschikt voor het tonen van enkele waarden of een minigrafiek. Large (364×382 pt) beslaat bijna de helft van het scherm verticaal en maakt het mogelijk tabellen, lijsten of uitgebreide gegevens weer te geven.

De ontwikkelaar moet ten minste twee formaten ondersteunen — Apple adviseert small + medium. Large-widget is alleen nodig als de app voldoende inhoud heeft om een dergelijk volume te vullen. Elk formaat krijgt zijn eigen SwiftUI-weergave die WidgetKit op het systeemscherm rendert. Het is belangrijk dat WidgetKit geen aangepaste formaten ondersteunt — alleen drie vaste, wat de uniformiteit van de interface garandeert.

Formaten configureren via 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])
    }
}

Widgetconfiguratietypen: Static en Intent

WidgetKit biedt twee configuratietypen — StaticConfiguration en IntentConfiguration. StaticConfiguration is geschikt voor widgets die dezelfde inhoud voor alle gebruikers tonen: wisselkoersen, weer, agenda. IntentConfiguration stelt de gebruiker in staat de widget aan te passen bij het toevoegen via het Siri-intentsysteem — bijvoorbeeld een specifieke stad selecteren voor het weer of een specifieke ticker voor de aandelenkoers.

IntentConfiguration gebruikt INWidgetIntent — een subklasse van INIntent uit SiriKit. Wanneer de gebruiker een widget toevoegt en parameters selecteert (bijvoorbeeld stad), slaat het systeem deze intent op en geeft deze bij elke update door aan TimelineProvider. De provider ontvangt de intent in de getTimeline-methode en gebruikt de parameters om inhoud te genereren. IntentConfiguration is de voorkeursmethode voor gepersonaliseerde widgets omdat het integreert met Siri en Shortcuts.

IntentConfiguration met parameterselectie

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

Een widget maken in SwiftUI: stapsgewijs voorbeeld

Het maken van een widget begint met het toevoegen van Widget Extension Target in Xcode: File → New → Target → Widget Extension. Xcode genereert automatisch een structuur met TimelineEntry, TimelineProvider en WidgetConfiguration. De ontwikkelaar hoeft alleen de SwiftUI-weergave voor het tonen van gegevens te implementeren en de provider te configureren voor een correct updateschema.

Hieronder — een volledig voorbeeld van een eenvoudige widget voor het weergeven van de huidige bitcoinprijs: Provider laadt de prijs via URLSession en maakt een Timeline met een update elk uur. WidgetSwiftUIView toont de prijs in een groot lettertype en de tijd van de laatste update in een klein lettertype.

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 voor vergrendelscherm iOS 16+

Vanaf iOS 16 heeft WidgetKit de ondersteuning uitgebreid naar Lock Screen — het vergrendelscherm van de iPhone. Lock Screen-widgets zijn er in twee typen: inline (een enkele tekstregel onder de klok) en rectangular (een rechthoekig gebied). In tegenstelling tot Home Screen-widgets worden Lock Screen-widgets vaker bijgewerkt — de systeemtrigger maakt updates elke 15–30 minuten mogelijk om actuele informatie te tonen zonder de telefoon te ontgrendelen.

Lock Screen-widgets vereisen een aparte configuratie via WidgetConfiguration met accessoryFamilies: accessoryCircular, accessoryRectangular, accessoryInline. Deze families hebben strikte beperkingen qua grootte en inhoud — ze ondersteunen geen afbeeldingen, animaties en aangepaste lettertypen. Apple raadt aan alleen tekstuele informatie en systeempictogrammen SF Symbols te gebruiken voor Lock Screen-widgets.

• accessoryCircular — compacte ronde widget voor de plek onder de klok
• accessoryRectangular — rechthoekige widget voor het gebied boven de klok
• accessoryInline — eenregelige tekst onder de tijd, minimaal formaat
• Beperkingen: alleen tekst, SF Symbols, verloop; geen afbeeldingen en video

Best practices en beperkingen van WidgetKit

Bij het ontwikkelen van widgets is het belangrijk rekening te houden met de beperkingen van WidgetKit. Widgets zijn alleen-lezen weergaven: ze verwerken geen aanraakgebeurtenissen (behalve tikken die de app opent). Widgets ondersteunen geen animatie, video, toetsenbordinvoer, scrollen of interactieve elementen. Elke widget is een statische momentopname van gegevens op een bepaald moment, en een poging om interactiviteit toe te voegen leidt tot afwijzing van de app in de App Store.

Best practices omvatten Widget Center voor geforceerde updates, het cachen van gegevens op TimelineProvider-niveau voor snelle respons en het gebruik van placeholders voor de beginstatus. Ook belangrijk is het ondersteunen van meerdere formaten — de gebruiker verwacht dat de widget beschikbaar is in zowel small als medium variant. Vermijd het tonen van onnauwkeurige of verouderde gegevens — de gebruiker onthoudt onjuiste informatie van de widget lang.

WidgetKit-beperkingen in tabel