WidgetKit — co to jest, framework widżetów i SwiftUI

Co to jest WidgetKit i jak działa?

WidgetKit — framework Apple do tworzenia widżetów, które wyświetlają treść na ekranach systemowych urządzeń Apple. Widżet to miniaturowe przedstawienie Twojej aplikacji, które użytkownik umieszcza na ekranie głównym w trybie „potrząsania” (jiggle mode). W przeciwieństwie do komplikacji watchOS, które istniały przed WidgetKit, nowy framework ujednolicił tworzenie widżetów dla wszystkich platform Apple poprzez jednolite API na SwiftUI.

Zasada działania WidgetKit opiera się na TimelineProvider — obiekcie, który tworzy uporządkowaną tablicę TimelineEntry, gdzie każdy wpis zawiera Snapshot (konkretny stan widżetu w określonym momencie czasu). System wyświetla wpisy sekwencyjnie, aktualizując widżet przy przejściu do następnego wpisu na osi czasu. Między wpisami WidgetKit nie wywołuje kodu aplikacji — czas procesora jest zużywany tylko przy tworzeniu nowego Timeline.

Według danych WWDC 2024 Session „WidgetKit: What’s new”, przeciętny użytkownik iOS ma na ekranie głównym 8–12 widżetów, a najpopularniejsze kategorie to pogoda, czas, kalendarz, fitness i finanse. WidgetKit zużywa mniej niż 1% baterii dziennie przy typowym użytkowaniu dzięki temu, że aktualizacje odbywają się według harmonogramu, a nie w czasie rzeczywistym.

Co odróżnia WidgetKit od starych Today Extension

Przed iOS 14 widżety istniały tylko w postaci Today View — panelu dostępnego przesunięciem w lewo od pierwszego ekranu. Today Extension miały poważne ograniczenia: były dostępne tylko na ekranie „Dzisiaj”, wymagały otwarcia aplikacji do aktualizacji treści i miały ograniczoną obsługę rozmiarów. WidgetKit całkowicie zastąpił Today Extension, zapewniając widżety na ekranie głównym, ekranie blokady (iOS 16+) i pulpicie Maca.

• Widżety na ekranie głównym, nie tylko w Today View
• Samodzielna aktualizacja przez TimelineProvider, bez otwierania aplikacji
• Trzy predefiniowane rozmiary zamiast jednego
• Smart Rotate i Smart Stack — automatyczna rotacja widżetów przez system
• Jednolite API na SwiftUI dla wszystkich platform Apple

Architektura WidgetKit: TimelineProvider i Entry

Architektura WidgetKit opiera się na trzech kluczowych protokołach: TimelineProvider, TimelineEntry i Widget. TimelineEntry to model danych reprezentujący stan widżetu w konkretnym momencie czasu. TimelineProvider tworzy tablicę takich wpisów (Timeline), podając datę aktywacji dla każdego. Widget — punkt wejścia, który łączy dostawcę z widokiem SwiftUI.

Metoda Timeline getTimeline jest wywoływana przez system przy pierwszym dodaniu widżetu, a następnie okresowo — zwykle co 1–6 godzin w zależności od typu dostawcy. Timeline może zawierać wpisy na godziny lub dni naprzód, co pozwala widżetowi działać bez wywoływania kodu aplikacji pomiędzy aktualizacjami. Jeśli konieczne jest pilne zaktualizowanie widżetu (np. zmienił się kurs waluty), aplikacja może wywołać WidgetCenter.shared.reloadAllTimelines() wymuszenie.

Podstawowy 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 obsługuje trzy rozmiary widżetów, z których każdy ma stałe proporcje. Small (170×170 pt na iPhone) wyświetla kompaktowe informacje — pojedynczą wartość, ikonę lub krótki tekst. Medium (364×170 pt) jest dwukrotnie szerszy od small i nadaje się do wyświetlania pary wartości lub mini-wykresu. Large (364×382 pt) zajmuje prawie połowę ekranu w pionie i umożliwia wyświetlanie tabel, list lub rozszerzonych danych.

Programista musi obsługiwać co najmniej dwa rozmiary — Apple zaleca small + medium. Widżet Large jest wymagany tylko wtedy, gdy aplikacja ma wystarczająco dużo treści, aby wypełnić taką objętość. Każdy rozmiar otrzymuje własny widok SwiftUI, który WidgetKit renderuje na ekranie systemowym. Ważne, że WidgetKit nie obsługuje niestandardowych rozmiarów — tylko trzy stałe, co gwarantuje jednolitość interfejsu.

Konfiguracja rozmiarów przez 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 konfiguracji widżetów: Static i Intent

WidgetKit oferuje dwa typy konfiguracji — StaticConfiguration i IntentConfiguration. StaticConfiguration jest odpowiedni dla widżetów, które wyświetlają tę samą treść dla wszystkich użytkowników: kursy walut, pogoda, kalendarz. IntentConfiguration pozwala użytkownikowi dostosować widżet podczas dodawania za pośrednictwem systemu intentów Siri — na przykład wybrać konkretne miasto dla pogody lub konkretny ticker dla kursu akcji.

IntentConfiguration używa INWidgetIntent — podklasy INIntent z SiriKit. Gdy użytkownik dodaje widżet i wybiera parametry (np. miasto), system zapisuje ten intent i przekazuje go do TimelineProvider przy każdej aktualizacji. Dostawca otrzymuje intent w metodzie getTimeline i używa jego parametrów do tworzenia treści. IntentConfiguration to preferowany sposób dla spersonalizowanych widżetów, ponieważ integruje się z Siri i Shortcuts.

IntentConfiguration z wyborem parametrów

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

Tworzenie widżetu w SwiftUI: przykład krok po kroku

Tworzenie widżetu rozpoczyna się od dodania Widget Extension Target w Xcode: File → New → Target → Widget Extension. Xcode automatycznie generuje strukturę z TimelineEntry, TimelineProvider i WidgetConfiguration. Programiście pozostaje tylko zaimplementować widok SwiftUI do wyświetlania danych i skonfigurować dostawcę do prawidłowego harmonogramu aktualizacji.

Poniżej — pełny przykład prostego widżetu do wyświetlania bieżącego kursu bitcoina: Provider ładuje kurs przez URLSession i tworzy Timeline z aktualizacją co godzinę. WidgetSwiftUIView wyświetla kurs dużą czcionką i czas ostatniej aktualizacji małą.

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

Widżety ekranu blokady iOS 16+

Od iOS 16 WidgetKit rozszerzył obsługę na Lock Screen — ekran blokady iPhone’a. Widżety Lock Screen są dwojakiego rodzaju: inline (pojedyncza linia tekstu pod zegarem) i rectangular (prostokątny obszar). W przeciwieństwie do widżetów Home Screen, widżety Lock Screen aktualizują się częściej — wyzwalacz systemowy pozwala aktualizować je co 15–30 minut, aby wyświetlać aktualne informacje bez odblokowywania telefonu.

Widżety Lock Screen wymagają oddzielnej konfiguracji przez WidgetConfiguration z accessoryFamilies: accessoryCircular, accessoryRectangular, accessoryInline. Te rodziny mają ścisłe ograniczenia co do rozmiaru i zawartości — nie obsługują obrazów, animacji ani niestandardowych czcionek. Apple zaleca używanie tylko informacji tekstowych i systemowych ikon SF Symbols dla widżetów Lock Screen.

• accessoryCircular — kompaktowy okrągły widżet do miejsca pod zegarem
• accessoryRectangular — prostokątny widżet dla obszaru nad zegarem
• accessoryInline — jedno-linijkowy tekst pod czasem, minimalny rozmiar
• Ograniczenia: tylko tekst, SF Symbols, gradienty; bez obrazów i wideo

Best practices i ograniczenia WidgetKit

Przy tworzeniu widżetów ważne jest uwzględnienie ograniczeń WidgetKit. Widżety to widoki tylko do odczytu: nie obsługują zdarzeń dotykowych (poza dotknięciem, które otwiera aplikację). Widżety nie obsługują animacji, wideo, wprowadzania z klawiatury, przewijania ani interaktywnych elementów. Każdy widżet to statyczny migawka danych w określonym momencie, a próba dodania interaktywności doprowadzi do odrzucenia aplikacji w App Store.

Najlepsze praktyki obejmują Widget Center do wymuszonej aktualizacji, buforowanie danych na poziomie TimelineProvider dla szybkiej odpowiedzi i używanie placeholder dla stanu początkowego. Ważne jest również obsługiwanie wielu rozmiarów — użytkownik oczekuje, że widżet będzie dostępny zarówno w wariancie small, jak i medium. Należy religiousnie unikać wyświetlania nieaktualnych lub niedokładnych danych — użytkownik zapamiętuje nieprawidłowe informacje z widżetu na długo.

Ograniczenia WidgetKit w tabeli