WidgetKit — ce este, framework widgeturi și SwiftUI

Ce este WidgetKit și cum funcționează?

WidgetKit — framework-ul Apple pentru crearea widgeturilor care afișează conținut pe ecranele de sistem ale dispozitivelor Apple. Un widget este o reprezentare miniaturală a aplicației dvs. pe care utilizatorul o plasează pe ecranul de pornire în modul de agitație (jiggle mode). Spre deosebire de complicațiile watchOS care existau înainte de WidgetKit, noul framework a unificat crearea widgeturilor pentru toate platformele Apple printr-o API unică pe SwiftUI.

Principiul de funcționare al WidgetKit se bazează pe TimelineProvider — un obiect care creează un array ordonat de TimelineEntry, unde fiecare înregistrare conține un Snapshot (starea specifică a widgetului la un moment dat). Sistemul afișează înregistrările secvențial, actualizând widgetul la trecerea la următoarea înregistrare pe axa temporală. Între înregistrări, WidgetKit nu apelează codul aplicației — timpul procesorului este consumat doar la crearea unui nou Timeline.

Conform datelor WWDC 2024 Session „WidgetKit: What’s new”, utilizatorul mediu de iOS are 8–12 widgeturi pe ecranul de pornire, iar cele mai populare categorii sunt meteo, timp, calendar, fitness și finanțe. WidgetKit consumă mai puțin de 1% din baterie pe zi în utilizare tipică datorită faptului că actualizările au loc conform unui program, nu în timp real.

Ce diferențiază WidgetKit de vechile Today Extension

Înainte de iOS 14, widgeturile existau doar sub formă de Today View — un panou accesibil prin glisarea la stânga de pe primul ecran. Today Extension aveau limitări serioase: erau disponibile doar pe ecranul „Astăzi”, necesitau deschiderea aplicației pentru actualizarea conținutului și aveau suport limitat pentru dimensiuni. WidgetKit a înlocuit complet Today Extension, oferind widgeturi pe ecranul de pornire, ecranul de blocare (iOS 16+) și desktop-ul Mac.

• Widgeturi pe ecranul de pornire, nu doar în Today View
• Actualizare autonomă prin TimelineProvider, fără deschiderea aplicației
• Trei dimensiuni predefinite în loc de una
• Smart Rotate și Smart Stack — rotația automată a widgeturilor de sistem
• API unic pe SwiftUI pentru toate platformele Apple

Arhitectura WidgetKit: TimelineProvider și Entry

Arhitectura WidgetKit se bazează pe trei protocoale cheie: TimelineProvider, TimelineEntry și Widget. TimelineEntry este un model de date care reprezintă starea widgetului la un moment specific. TimelineProvider creează un array de astfel de înregistrări (Timeline), specificând data de activare pentru fiecare. Widget — punctul de intrare care leagă furnizorul de vizualizarea SwiftUI.

Metoda getTimeline este apelată de sistem la prima adăugare a widgetului și apoi periodic — de obicei la fiecare 1–6 ore în funcție de tipul furnizorului. Timeline poate conține înregistrări pentru ore sau zile în avans, permițând widgetului să funcționeze fără a apela codul aplicației între actualizări. Dacă este necesară actualizarea urgentă a widgetului (de exemplu, s-a schimbat cursul valutar), aplicația poate apela WidgetCenter.shared.reloadAllTimelines() forțat.

TimelineProvider de bază

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 suportă trei dimensiuni de widgeturi, fiecare având proporții fixe. Small (170×170 pt pe iPhone) afișează informații compacte — o singură valoare, pictogramă sau text scurt. Medium (364×170 pt) este de două ori mai lat decât small și este potrivit pentru afișarea a câtorva valori sau a unui mini-grafic. Large (364×382 pt) ocupă aproape jumătate din ecran pe verticală și permite afișarea tabelelor, listelor sau datelor extinse.

Dezvoltatorul trebuie să suporte cel puțin două dimensiuni — Apple recomandă small + medium. Widgetul Large este necesar doar dacă aplicația are suficient conținut pentru a umple un astfel de volum. Fiecare dimensiune primește propria vizualizare SwiftUI pe care WidgetKit o randarează pe ecranul de sistem. Este important că WidgetKit nu suportă dimensiuni personalizate — doar trei fixe, ceea ce garantează uniformitatea interfeței.

Configurarea dimensiunilor prin 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])
    }
}

Tipuri de configurare a widgeturilor: Static și Intent

WidgetKit oferă două tipuri de configurare — StaticConfiguration și IntentConfiguration. StaticConfiguration este potrivit pentru widgeturile care afișează același conținut pentru toți utilizatorii: cursuri valutare, meteo, calendar. IntentConfiguration permite utilizatorului să personalizeze widgetul la adăugare prin sistemul de intent-uri Siri — de exemplu, să selecteze un oraș specific pentru meteo sau un ticker specific pentru cursul acțiunilor.

IntentConfiguration folosește INWidgetIntent — o subclasă a INIntent din SiriKit. Când utilizatorul adaugă un widget și selectează parametri (de exemplu, orașul), sistemul salvează acest intent și îl transmite TimelineProvider la fiecare actualizare. Furnizorul primește intent-ul în metoda getTimeline și folosește parametrii săi pentru a genera conținut. IntentConfiguration este metoda preferată pentru widgeturile personalizate, deoarece se integrează cu Siri și Shortcuts.

IntentConfiguration cu selectarea parametrilor

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

Crearea unui widget în SwiftUI: exemplu pas cu pas

Crearea unui widget începe cu adăugarea Widget Extension Target în Xcode: File → New → Target → Widget Extension. Xcode generează automat o structură cu TimelineEntry, TimelineProvider și WidgetConfiguration. Dezvoltatorului îi rămâne doar să implementeze vizualizarea SwiftUI pentru afișarea datelor și să configureze furnizorul pentru un program corect de actualizări.

Mai jos — un exemplu complet al unui widget simplu pentru afișarea cursului curent al bitcoinului: Provider încarcă cursul prin URLSession și creează un Timeline cu actualizare la fiecare oră. WidgetSwiftUIView afișează cursul cu un font mare și timpul ultimei actualizări cu un font mic.

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

Widgeturi ecran blocare iOS 16+

începând cu iOS 16, WidgetKit a extins suportul pentru Lock Screen — ecranul de blocare al iPhone-ului. Widgeturile Lock Screen sunt de două tipuri: inline (un rând de text sub ceas) și rectangular (o zonă dreptunghiulară). Spre deosebire de widgeturile Home Screen, widgeturile Lock Screen se actualizează mai frecvent — declanșatorul de sistem permite actualizarea lor la fiecare 15–30 de minute pentru afișarea informațiilor actuale fără deblocarea telefonului.

Widgeturile Lock Screen necesită o configurare separată prin WidgetConfiguration cu accessoryFamilies: accessoryCircular, accessoryRectangular, accessoryInline. Aceste familii au restricții stricte de dimensiune și conținut — nu suportă imagini, animație și fonturi personalizate. Apple recomandă utilizarea doar a informațiilor text și a pictogramelor de sistem SF Symbols pentru widgeturile Lock Screen.

• accessoryCircular — widget circular compact pentru locul de sub ceas
• accessoryRectangular — widget dreptunghiular pentru zona de deasupra ceasului
• accessoryInline — text pe un rând sub timp, dimensiune minimă
• Restricții: doar text, SF Symbols, gradiente; fără imagini și video

Best practices și limitări WidgetKit

La dezvoltarea widgeturilor este important să se țină cont de limitările WidgetKit. Widgeturile sunt vizualizări doar pentru citire: nu procesează evenimente tactile (cu excepția atingerii care deschide aplicația). Widgeturile nu suportă animație, video, introducere de la tastatură, derulare sau elemente interactive. Fiecare widget este o imagine statică a datelor la un moment dat, iar încercarea de a adăuga interactivitate va duce la respingerea aplicației în App Store.

Cele mai bune practici includ Widget Center pentru actualizare forțată, stocarea în cache a datelor la nivelul TimelineProvider pentru răspuns rapid și utilizarea de placeholder pentru starea inițială. De asemenea, este important să suportați mai multe dimensiuni — utilizatorul se așteaptă ca widgetul să fie disponibil atât în varianta small, cât și medium. Evitați cu strictețe afișarea datelor inexacte sau învechite — utilizatorul își amintește informațiile incorecte din widget pentru mult timp.

Limitările WidgetKit în tabel