WidgetKit — co to je, framework widgetů a SwiftUI

Co je WidgetKit a jak funguje?

WidgetKit — framework Apple pro vytváření widgetů, které zobrazují obsah na systémových obrazovkách zařízení Apple. Widget je miniaturní zobrazení vaší aplikace, které uživatel umístí na domovskou obrazovku v režimu třesení (jiggle mode). Na rozdíl od watchOS komplikací, které existovaly před WidgetKit, nový framework sjednotil vytváření widgetů pro všechny platformy Apple prostřednictvím jednotného API na SwiftUI.

Princip fungování WidgetKit je založen na TimelineProvider — objektu, který vytváří seřazené pole TimelineEntry, kde každý záznam obsahuje Snapshot (konkrétní stav widgetu v určitém časovém okamžiku). Systém zobrazuje záznamy postupně, aktualizuje widget při přechodu na další záznam na časové ose. Mezi záznamy WidgetKit nevolá kód aplikace — čas procesoru se spotřebovává pouze při vytváření nového Timeline.

Podle údajů WWDC 2024 Session „WidgetKit: What’s new” má průměrný uživatel iOS 8–12 widgetů na domovské obrazovce a nejoblíbenější kategorie jsou počasí, čas, kalendář, fitness a finance. WidgetKit spotřebovává měně než 1% baterie denně při běžném používání, protože aktualizace probíhají podle plánu, ne v reálném čase.

Co odlišuje WidgetKit od starých Today Extension

Před iOS 14 existovaly widgety pouze jako Today View — panel přístupný přetažním doleva z první obrazovky. Today Extension měly vážná omezení: byly dostupné pouze na obrazovce „Dnes”, vyžadovaly otevření aplikace pro aktualizaci obsahu a měly omezenou podporu velikostí. WidgetKit zcela nahradil Today Extension a poskytuje widgety na domovské obrazovce, zámku obrazovky (iOS 16+) a pracovní ploše Macu.

• Widgety na domovské obrazovce, nejen v Today View
• Autonomní aktualizace prostřednictvím TimelineProvider bez otevření aplikace
• Tři předdefinované velikosti místo jedné
• Smart Rotate a Smart Stack — automatická rotace widgetů systémem
• Jednotné API na SwiftUI pro všechny platformy Apple

Architektura WidgetKit: TimelineProvider a Entry

Architektura WidgetKit je založena na třech klíčových protokolech: TimelineProvider, TimelineEntry a Widget. TimelineEntry je datový model představující stav widgetu v konkrétním časovém okamžiku. TimelineProvider vytváří pole takových záznamů (Timeline) s uvedením data aktivace pro každý. Widget — vstupní bod, který spojuje poskytovatele s zobrazením SwiftUI.

Metoda getTimeline je volána systémem při prvním přidání widgetu a poté periodicky — obvykle každých 1–6 hodin v závislosti na typu poskytovatele. Timeline může obsahovat záznamy na hodiny nebo dny dopředu, což umožňuje widgetu pracovat bez volání kódu aplikace mezi aktualizacemi. Pokud je třeba widget naléhavě aktualizovat (např. změnil se kurz měny), aplikace může vynuceně zavolat WidgetCenter.shared.reloadAllTimelines().

Základní 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 podporuje tři velikosti widgetů, každá s pevnými proporcemi. Small (170×170 pt na iPhonu) zobrazuje kompaktní informace — jednu hodnotu, ikonu nebo krátký text. Medium (364×170 pt) je dvakrát širší než small a hodí se pro zobrazení několika hodnot nebo mini-grafu. Large (364×382 pt) zabírá téměř polovinu obrazovky na výšku a umožňuje zobrazení tabulek, seznamů nebo rozšířených dat.

Vývojář musí podporovat alespoň dvě velikosti — Apple doporučuje small + medium. Large widget je vyžadován pouze v případě, že aplikace má dostatek obsahu k vyplnění takového objemu. Každá velikost získá vlastní zobrazení SwiftUI, které WidgetKit vykreslí na systémové obrazovce. Je důležité, že WidgetKit nepodporuje vlastní velikosti — pouze tři pevné, což zaručuje jednotnost rozhraní.

Konfigurace velikostí prostřednictvím 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])
    }
}

Typy konfigurace widgetů: Static a Intent

WidgetKit nabízí dva typy konfigurace — StaticConfiguration a IntentConfiguration. StaticConfiguration je vhodný pro widgety, které zobrazují stejný obsah pro všechny uživatele: kurzy měn, počasí, kalendář. IntentConfiguration umožňuje uživateli přizpůsobit widget při přidání prostřednictvím systému intentů Siri — například vybrat konkrétní město pro počasí nebo konkrétní ticker pro cenu akcie.

IntentConfiguration používá INWidgetIntent — podtřídu INIntent ze SiriKit. Když uživatel přidá widget a vybere parametry (např. město), systém uloží tento intent a při každé aktualizaci jej předá TimelineProvider. Poskytovatel obdrží intent v metodě getTimeline a použije jeho parametry k vytvoření obsahu. IntentConfiguration je preferovaným způsobem pro personalizované widgety, protože se integruje se Siri a Shortcuts.

IntentConfiguration s výběrem parametrů

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

Vytvoření widgetu ve SwiftUI: příklad krok za krokem

Vytvoření widgetu začíná přidáním Widget Extension Target v Xcode: File → New → Target → Widget Extension. Xcode automaticky generuje strukturu s TimelineEntry, TimelineProvider a WidgetConfiguration. Vývojáři zbývá pouze implementovat zobrazení SwiftUI pro zobrazení dat a nakonfigurovat poskytovatele pro správný plán aktualizací.

Níže — úplný příklad jednoduchého widgetu pro zobrazení aktuální ceny bitcoinu: Provider načte cenu prostřednictvím URLSession a vytvoří Timeline s aktualizací každou hodinu. WidgetSwiftUIView zobrazuje cenu velkým písmem a čas poslední aktualizace malým písmem.

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

Widgety zámku obrazovky iOS 16+

Od iOS 16 WidgetKit rozšířil podporu na Lock Screen — zámek obrazovky iPhonu. Widgety Lock Screen jsou dvou typů: inline (jeden řádek textu pod hodinami) a rectangular (obdélníková oblast). Na rozdíl od widgetů Home Screen se widgety Lock Screen aktualizují častěji — systémová spoušť umožňuje aktualizaci každých 15–30 minut pro zobrazení aktuálních informací bez odemčení telefonu.

Widgety Lock Screen vyžadují samostatnou konfiguraci prostřednictvím WidgetConfiguration s accessoryFamilies: accessoryCircular, accessoryRectangular, accessoryInline. Tyto rodiny mají přísná omezení velikosti a obsahu — nepodporují obrázky, animace a vlastní písma. Apple doporučuje používat pouze textové informace a systémové ikony SF Symbols pro widgety Lock Screen.

• accessoryCircular — kompaktní kruhový widget pro místo pod hodinami
• accessoryRectangular — obdélníkový widget pro oblast nad hodinami
• accessoryInline — jednořádkový text pod časem, minimální velikost
• Omezení: pouze text, SF Symbols, přechody; bez obrázků a videa

Osvědčené postupy a omezení WidgetKit

Při vývoji widgetů je důležité brát v úvahu omezení WidgetKit. Widgety jsou zobrazení pouze pro čtení: nezpracovávají dotykové události (kromě klepnutí, které otevírá aplikaci). Widgety nepodporují animace, video, vstup z klávesnice, rolování nebo interaktivní prvky. Každý widget je statický snímek dat v určitém časovém okamžiku a pokus o přidání interaktivity povede k zamítnutí aplikace v App Store.

Osvědčené postupy zahrnují Widget Center pro vynucenou aktualizaci, ukládání dat do mezipaměti na úrovni TimelineProvider pro rychlou odezvu a použití placeholder pro počáteční stav. Také je důležité podporovat více velikostí — uživatel očekává, že widget bude dostupný jak ve variantě small, tak medium. Důsledně se vyhýbejte zobrazení nepřesných nebo zastaralých dat — uživatel si pamatuje nesprávné informace z widgetu po dlouhou dobu.

Omezení WidgetKit v tabulce