WidgetKit — cos'è, framework di widget e SwiftUI

Cos'è WidgetKit e come funziona?

WidgetKit è un framework Apple per creare widget che mostrano contenuti sulle schermate di sistema dei dispositivi Apple. Un widget è una rappresentazione in miniatura della tua app che l'utente posiziona sulla schermata home in modalità jiggle. A differenza delle complicazioni watchOS che esistevano prima di WidgetKit, il nuovo framework ha unificato la creazione di widget per tutte le piattaforme Apple attraverso un'unica API basata su SwiftUI.

Il principio di funzionamento di WidgetKit si basa su TimelineProvider — un oggetto che crea un array ordinato di TimelineEntry, dove ogni entry contiene un Snapshot (uno stato specifico del widget in un determinato momento). Il sistema mostra le entry in sequenza, aggiornando il widget quando si passa alla entry successiva sulla timeline. Tra le entry, WidgetKit non chiama il codice dell'app — il tempo CPU viene speso solo durante la creazione di una nuova Timeline.

Secondo la sessione WWDC 2024 “WidgetKit: What’s new”, l'utente iOS medio ha 8–12 widget sulla schermata home, e le categorie più popolari sono meteo, ora, calendario, fitness e finanza. WidgetKit consuma meno dell'1% di carica della batteria al giorno con un utilizzo tipico, grazie ad aggiornamenti programmati invece che in tempo reale.

Cosa distingue WidgetKit dalle vecchie Today Extensions

Prima di iOS 14, i widget esistevano solo come Today View — un pannello accessibile scorrendo verso sinistra dalla prima schermata. Le Today Extensions avevano limitazioni serie: erano disponibili solo sulla schermata “Oggi”, richiedevano l'apertura dell'app per aggiornare il contenuto e avevano un supporto limitato delle dimensioni. WidgetKit ha completamente sostituito le Today Extensions, fornendo widget sulla schermata home, sulla schermata di blocco (iOS 16+) e sul desktop di Mac.

• Widget sulla schermata home, non solo in Today View
• Aggiornamento autonomo tramite TimelineProvider, senza aprire l'app
• Tre dimensioni predefinite invece di una
• Smart Rotate e Smart Stack — rotazione automatica dei widget da parte del sistema
• API unificata in SwiftUI per tutte le piattaforme Apple

Architettura di WidgetKit: TimelineProvider e Entry

L'architettura di WidgetKit si basa su tre protocolli chiave: TimelineProvider, TimelineEntry e Widget. TimelineEntry è un modello di dati che rappresenta lo stato del widget in un momento specifico. TimelineProvider crea un array di tali entry (Timeline), specificando la data di attivazione per ciascuna. Widget è il punto di ingresso che collega il provider alla vista SwiftUI.

Il metodo Timeline getTimeline viene chiamato dal sistema quando il widget viene aggiunto per la prima volta e poi periodicamente — di solito ogni 1–6 ore a seconda del tipo di provider. Una Timeline può contenere entry per ore o giorni in anticipo, consentendo al widget di funzionare senza chiamare il codice dell'app tra gli aggiornamenti. Se è necessario un aggiornamento urgente (ad esempio, il tasso di cambio è cambiato), l'app può chiamare forzatamente WidgetCenter.shared.reloadAllTimelines().

TimelineProvider di base

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 supporta tre dimensioni di widget, ciascuna con proporzioni fisse. Small (170×170 pt su iPhone) mostra informazioni compatte — un singolo valore, icona o testo breve. Medium (364×170 pt) è largo il doppio di small ed è adatto per mostrare coppie di valori o mini-grafici. Large (364×382 pt) occupa quasi metà dello schermo in verticale e consente di mostrare tabelle, elenchi o dati espansi.

Lo sviluppatore deve supportare almeno due dimensioni — Apple consiglia small + medium. Il widget Large è necessario solo se l'app ha abbastanza contenuti per riempire quel volume. Ogni dimensione ottiene la propria SwiftUI View, che WidgetKit renderizza sulla schermata di sistema. È importante che WidgetKit non supporta dimensioni personalizzate — solo tre dimensioni fisse, garantendo l'uniformità dell'interfaccia.

Configurazione delle dimensioni tramite 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])
    }
}

Tipi di configurazione dei widget: Static e Intent

WidgetKit offre due tipi di configurazione — StaticConfiguration e IntentConfiguration. StaticConfiguration è adatto per widget che mostrano lo stesso contenuto per tutti gli utenti: tassi di cambio, meteo, calendario. IntentConfiguration consente all'utente di personalizzare il widget durante l'aggiunta tramite il sistema di intent di Siri — ad esempio, selezionare una città specifica per il meteo o un ticker specifico per il prezzo delle azioni.

IntentConfiguration utilizza INWidgetIntent — una sottoclasse di INIntent di SiriKit. Quando l'utente aggiunge un widget e seleziona parametri (ad esempio, città), il sistema salva questo intent e lo passa a TimelineProvider a ogni aggiornamento. Il provider riceve l'intent nel metodo getTimeline e utilizza i suoi parametri per formare il contenuto. IntentConfiguration è l'approccio preferito per widget personalizzati poiché si integra con Siri e Shortcuts.

IntentConfiguration con selezione dei parametri

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

Creazione di un widget in SwiftUI: esempio passo passo

La creazione di un widget inizia con l'aggiunta di un Widget Extension Target in Xcode: File → New → Target → Widget Extension. Xcode genera automaticamente una struttura con TimelineEntry, TimelineProvider e WidgetConfiguration. Lo sviluppatore deve solo implementare la SwiftUI View per visualizzare i dati e configurare il provider per una corretta pianificazione degli aggiornamenti.

Di seguito è riportato un esempio completo di un semplice widget per mostrare il prezzo attuale di Bitcoin: Provider carica il tasso tramite URLSession e crea una Timeline con aggiornamenti ogni ora. WidgetSwiftUIView mostra il tasso in carattere grande e l'ora dell'ultimo aggiornamento in carattere piccolo.

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 ? "+" : "")
        }
    }
}

Widget schermata di blocco iOS 16+

Con iOS 16, WidgetKit ha esteso il supporto alla Schermata di blocco — la schermata di blocco dell'iPhone. I widget della schermata di blocco sono di due tipi: inline (una singola riga di testo sotto l'orologio) e rectangular (un'area rettangolare). A differenza dei widget della schermata home, i widget della schermata di blocco vengono aggiornati più frequentemente — il trigger di sistema consente aggiornamenti ogni 15–30 minuti per mostrare informazioni aggiornate senza sbloccare il telefono.

I widget della schermata di blocco richiedono una configurazione separata tramite WidgetConfiguration con accessoryFamilies: accessoryCircular, accessoryRectangular, accessoryInline. Queste famiglie hanno severe limitazioni di dimensione e contenuto — non supportano immagini, animazioni o caratteri personalizzati. Apple consiglia di utilizzare solo informazioni testuali e icone di sistema SF Symbols per i widget della schermata di blocco.

• accessoryCircular — widget circolare compatto per l'area sotto l'orologio
• accessoryRectangular — widget rettangolare per l'area sopra l'orologio
• accessoryInline — testo a riga singola sotto l'ora, dimensione minima
• Limitazioni: solo testo, SF Symbols, gradienti; senza immagini o video

Best practice e limitazioni di WidgetKit

Nello sviluppo di widget, è importante considerare le limitazioni di WidgetKit. I widget sono viste di sola lettura: non gestiscono eventi touch (tranne un tocco che apre l'app). I widget non supportano animazioni, video, input da tastiera, scorrimento o elementi interattivi. Ogni widget è un'istantanea statica di dati in un determinato momento e tentare di aggiungere interattività comporterà il rifiuto dell'app dall'App Store.

Le best practice includono l'uso di Widget Center per aggiornamenti forzati, la memorizzazione nella cache dei dati a livello di TimelineProvider per una risposta rapida e l'uso di placeholder per lo stato iniziale. È anche importante supportare più dimensioni — gli utenti si aspettano che il widget sia disponibile sia nella variante small che medium. Evita rigorosamente di mostrare dati imprecisi o obsoleti — gli utenti ricordano a lungo le informazioni errate dai widget.

Tabella delle limitazioni di WidgetKit