WidgetKit — mi ez, widget keretrendszer és SwiftUI

Mi az a WidgetKit és hogyan működik?

WidgetKit — az Apple keretrendszere olyan widgetek létrehozásához, amelyek tartalmat jelenítenek meg az Apple eszközök rendszerképernyőin. A widget az alkalmazás miniatűr reprezentációja, amelyet a felhasználó a kezdőképernyőn helyez el „rázogatás” módban (jiggle mode). A WidgetKit előtt létező watchOS komplikációkkal ellentétben az új keretrendszer egységesítette a widgetek létrehozását az összes Apple platform számára egy egységes SwiftUI API-n keresztül.

A WidgetKit működési elve a TimelineProvider-en alapul — egy objektumon, amely rendezett TimelineEntry tömböt hoz létre, ahol minden bejegyzés egy Snapshot-ot (a widget adott időpontbeli állapotát) tartalmaz. A rendszer szekvenciálisan jeleníti meg a bejegyzéseket, frissítve a widgetet a következő bejegyzésre való áttéréskor az idővonalon. A bejegyzések között a WidgetKit nem hívja meg az alkalmazás kódját — a processzoridő csak új Timeline létrehozásakor kerül felhasználásra.

A WWDC 2024 Session „WidgetKit: What’s new” adatai szerint az átlagos iOS-felhasználónak 8–12 widget van a kezdőképernyőjén, és a legnépszerűbb kategóriák az időjárás, idő, naptár, fitness és pénzügy. A WidgetKit kevesebb mint 1% akkumulátort fogyaszt naponta tipikus használat mellett, mivel a frissítések ütemezés szerint történnek, nem valós időben.

Mi különbözteti meg a WidgetKit-et a régi Today Extension-től

Az iOS 14 előtt a widgetek csak Today View formájában léteztek — egy panel, amely az első képernyőről balra húzással volt elérhető. A Today Extension-nek komoly korlátozásai voltak: csak a „Ma” képernyőn voltak elérhetők, megkövetelték az alkalmazás megnyitását a tartalom frissítéséhez, és korlátozott mérettámogatással rendelkeztek. A WidgetKit teljesen felváltotta a Today Extension-t, widgeteket biztosítva a kezdőképernyőn, a zárolt képernyőn (iOS 16+) és a Mac asztalán.

• Widgetek a kezdőképernyőn, nem csak a Today View-ban
• Autonóm frissítés TimelineProvider-en keresztül, az alkalmazás megnyitása nélkül
• Három előre meghatározott méret egy helyett
• Smart Rotate és Smart Stack — a widgetek automatikus forgatása a rendszer által
• Egységes SwiftUI API az összes Apple platformhoz

WidgetKit architektúra: TimelineProvider és Entry

A WidgetKit architektúrája három kulcsprotokollon alapul: TimelineProvider, TimelineEntry és Widget. A TimelineEntry egy adatmodell, amely a widget állapotát reprezentálja egy adott időpontban. A TimelineProvider létrehozza az ilyen bejegyzések tömbjét (Timeline), mindegyikhez aktiválási dátumot rendelve. A Widget — a belépési pont, amely összeköti a szolgáltatót a SwiftUI nézettel.

A getTimeline metódust a rendszer hívja meg a widget első hozzáadásakor, majd időszakosan — általában 1–6 óránként a szolgáltató típusától függően. A Timeline tartalmazhat bejegyzéseket órákra vagy napokra előre, lehetővé téve a widget számára, hogy a frissítések között az alkalmazás kódjának meghívása nélkül működjön. Ha a widgetet sürgősen frissíteni kell (pl. megváltozott a devizaárfolyam), az alkalmazás kényszerítve meghívhatja a WidgetCenter.shared.reloadAllTimelines() metódust.

Alap 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

A WidgetKit három widgetméretet támogat, mindegyik rögzített arányokkal. A Small (170×170 pt iPhone-on) kompakt információkat jelenít meg — egyetlen értéket, ikont vagy rövid szöveget. A Medium (364×170 pt) kétszer olyan széles, mint a small, és alkalmas néhány érték vagy mini-grafikon megjelenítésére. A Large (364×382 pt) függőlegesen a képernyő majdnem felét foglalja el, és lehetővé teszi táblázatok, listák vagy kiterjesztett adatok megjelenítését.

A fejlesztőnek legalább két méretet kell támogatnia — az Apple a small + medium kombinációt ajánlja. Large widget csak akkor szükséges, ha az alkalmazásnak elegendő tartalma van egy ekkora mennyiség kitöltéséhez. Minden méret saját SwiftUI nézetet kap, amelyet a WidgetKit a rendszerképernyőn jelenít meg. Fontos, hogy a WidgetKit nem támogat egyedi méreteket — csak három rögzítettet, ami garantálja a felület egységességét.

Méretek konfigurálása WidgetConfiguration segítségével

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 konfigurációs típusok: Static és Intent

A WidgetKit két konfigurációs típust kínál — StaticConfiguration és IntentConfiguration. A StaticConfiguration olyan widgetekhez alkalmas, amelyek ugyanazt a tartalmat jelenítik meg minden felhasználó számára: devizaárfolyamok, időjárás, naptár. Az IntentConfiguration lehetővé teszi a felhasználó számára, hogy a widgetet a hozzáadáskor testre szabja a Siri intent rendszeren keresztül — például kiválaszthasson egy adott várost az időjáráshoz vagy egy adott tickert a részvényárfolyamhoz.

Az IntentConfiguration az INWidgetIntent-et használja — az INIntent alosztályát a SiriKit-ből. Amikor a felhasználó hozzáad egy widgetet és kiválaszt paramétereket (pl. város), a rendszer elmenti ezt az intentet, és minden frissítéskor továbbítja a TimelineProvider-nek. A szolgáltató megkapja az intentet a getTimeline metódusban, és annak paramétereit használja a tartalom létrehozásához. Az IntentConfiguration a preferált módszer a személyre szabott widgetekhez, mivel integrálódik a Siri-vel és a Shortcuts-szal.

IntentConfiguration paraméterválasztással

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

Widget létrehozása SwiftUI-ben: lépésről lépésre példa

A widget létrehozása a Widget Extension Target hozzáadásával kezdődik az Xcode-ban: File → New → Target → Widget Extension. Az Xcode automatikusan létrehoz egy struktúrát TimelineEntry-vel, TimelineProvider-rel és WidgetConfiguration-nel. A fejlesztőnek már csak a SwiftUI nézetet kell implementálnia az adatok megjelenítéséhez és konfigurálnia a szolgáltatót a megfelelő frissítési ütemezéshez.

Alább — egy egyszerű widget teljes példája a bitcoin aktuális árfolyamának megjelenítéséhez: A Provider betölti az árfolyamot URLSession segítségével, és létrehoz egy Timeline-t óránkénti frissítéssel. A WidgetSwiftUIView nagy betűmérettel jeleníti meg az árfolyamot, az utolsó frissítés idejét pedig kis betűmérettel.

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

Zárolt képernyő widgetek iOS 16+

Az iOS 16-tól kezdve a WidgetKit kiterjesztette a támogatást a Lock Screen — az iPhone zárolt képernyőjére. A Lock Screen widgetek két típusúak: inline (egy sor szöveg az óra alatt) és rectangular (téglalap alakú terület). A Home Screen widgetektől eltérően a Lock Screen widgetek gyakrabban frissülnek — a rendszer trigger lehetővé teszi a frissítést 15–30 percenként, hogy aktuális információkat jelenítsenek meg a telefon feloldása nélkül.

A Lock Screen widgetek külön konfigurációt igényelnek a WidgetConfiguration segítségével accessoryFamilies paraméterrel: accessoryCircular, accessoryRectangular, accessoryInline. Ezek a családok szigorú méret- és tartalmi korlátozásokkal rendelkeznek — nem támogatják a képeket, animációt és egyedi betűtípusokat. Az Apple csak szöveges információk és rendszerikonok (SF Symbols) használatát ajánlja a Lock Screen widgetekhez.

• accessoryCircular — kompakt kör alakú widget az óra alatti helyre
• accessoryRectangular — téglalap alakú widget az óra feletti területre
• accessoryInline — egysoros szöveg az idő alatt, minimális méret
• Korlátozások: csak szöveg, SF Symbols, gradiensek; képek és videó nélkül

WidgetKit bevált gyakorlatok és korlátozások

A widgetek fejlesztésekor fontos figyelembe venni a WidgetKit korlátozásait. A widgetek csak olvasható nézetek: nem dolgozzák fel az érintési eseményeket (kivéve a koppintást, amely megnyitja az alkalmazást). A widgetek nem támogatják az animációt, videót, billentyűzetbevitelt, görgetést vagy interaktív elemeket. Minden widget az adatok statikus pillanatképe egy adott időpontban, és az interaktivitás hozzáadásának kísérlete az alkalmazás elutasításához vezet az App Store-ban.

A bevált gyakorlatok magukban foglalják a Widget Center használatát kényszerített frissítéshez, az adatok gyorsítótárazását a TimelineProvider szintjén a gyors válasz érdekében, és a placeholder használatát a kezdeti állapothoz. Szintén fontos több méret támogatása — a felhasználó elvárja, hogy a widget elérhető legyen mind small, mind medium változatban. Kerülje a pontatlan vagy elavult adatok megjelenítését — a felhasználó hosszú ideig emlékszik a widgetből származó hibás információkra.

A WidgetKit korlátozásai táblázatban