WidgetKit — шта је то, фрејмворк виџета и SwiftUI

Шта је WidgetKit и како ради?

WidgetKit — Apple фрејмворк за креирање виџета који приказују садржај на системским екранима Apple уређаја. Виџет је минијатурни приказ ваше апликације који корисник поставља на почетни екран у режиму „трешења“ (jiggle mode). За разлику од watchOS компликација које су постојале пре WidgetKit-а, нови фрејмворк је ујединио креирање виџета за све Apple платформе кроз јединствени API на SwiftUI-ју.

Принцип рада WidgetKit-а заснива се на TimelineProvider-у — објекту који креира уређени низ TimelineEntry-ја, где сваки унос садржи Snapshot (конкретно стање виџета у одређеном тренутку). Систем приказује уносе секвенцијално, ажурирајући виџет при преласку на следећи унос на временској линији. Између уноса, WidgetKit не позива код апликације — процесорско време се троши само при креирању новог Timeline-а.

Према подацима WWDC 2024 Session „WidgetKit: What's new", просечан iOS корисник има 8–12 виџета на почетном екрану, а најпопуларније категорије су време, сат, календар, фитнес и финансије. WidgetKit троши мање од 1% батерије дневно при типичном коришћењу захваљујући томе што се ажурирања одвијају по распореду, а не у реалном времену.

Шта разликује WidgetKit од старих Today Extension-а

Пре iOS 14, виџети су постојали само у облику Today View-а — панела доступног превлачењем улево са првог екрана. Today Extension су имали озбиљна ограничења: били су доступни само на екрану „Данас", захтевали су отварање апликације за ажурирање садржаја и имали су ограничену подршку за величине. WidgetKit је у потпуности заменио Today Extension, пружајући виџете на почетном екрану, екрану закључавања (iOS 16+) и радној површини Mac-а.

• Виџети на почетном екрану, не само у Today View-у
• Самостално ажурирање кроз TimelineProvider, без отварања апликације
• Три унапред дефинисане величине уместо једне
• Smart Rotate и Smart Stack — аутоматска ротација виџета од стране система
• Јединствени API на SwiftUI-ју за све Apple платформе

Архитектура WidgetKit-а: TimelineProvider и Entry

Архитектура WidgetKit-а се заснива на три кључна протокола: TimelineProvider, TimelineEntry и Widget. TimelineEntry је модел података који представља стање виџета у одређеном тренутку. TimelineProvider креира низ таквих уноса (Timeline), наводећи датум активације за сваки. Widget — улазна тачка која повезује провајдера са SwiftUI приказом.

Метод getTimeline се позива од стране система при првом додавању виџета, а затим периодично — обично сваких 1–6 сати у зависности од типа провајдера. Timeline може садржати уносе за сате или дане унапред, што омогућава виџету да ради без позивања кода апликације између ажурирања. Ако је потребно хитно ажурирати виџет (нпр. променио се курс валута), апликација може позвати WidgetCenter.shared.reloadAllTimelines() принудно.

Основни 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 подржава три величине виџета, од којих свака има фиксне пропорције. Small (170×170 pt на iPhone-у) приказује компактне информације — једну вредност, икону или кратак текст. Medium (364×170 pt) је дупло шири од small-а и погодан је за приказ пар вредности или мини-графика. Large (364×382 pt) заузима скоро половину екрана по вертикали и омогућава приказ табела, листи или проширених података.

Програмер мора подржавати бар две величине — Apple препоручује small + medium. Large виџет је потребан само ако апликација има довољно садржаја да попуни такав обим. Свака величина добија сопствени SwiftUI приказ који WidgetKit рендерује на системском екрану. Важно је да WidgetKit не подржава прилагођене величине — само три фиксне, што гарантује једнообразност интерфејса.

Конфигурација величина кроз 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])
    }
}

Типови конфигурације виџета: Static и Intent

WidgetKit нуди два типа конфигурације — StaticConfiguration и IntentConfiguration. StaticConfiguration је погодан за виџете који приказују исти садржај за све кориснике: курсеве валута, време, календар. IntentConfiguration омогућава кориснику да прилагоди виџет при додавању кроз систем интента Siri-ja — на пример, да изабере одређени град за време или одређени тикер за курс акција.

IntentConfiguration користи INWidgetIntent — подкласу INIntent-а из SiriKit-а. Када корисник дода виџет и изабере параметре (нпр. град), систем чува овај интент и прослеђује га TimelineProvider-у при сваком ажурирању. Провајдер прима интент у методи getTimeline и користи његове параметре за формирање садржаја. IntentConfiguration је пожељан начин за персонализоване виџете, јер се интегрише са Siri-јем и Shortcuts-има.

IntentConfiguration са избором параметара

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

Креирање виџета у SwiftUI-ју: пример корак по корак

Креирање виџета почиње додавањем Widget Extension Target-а у Xcode-у: File → New → Target → Widget Extension. Xcode аутоматски генерише структуру са TimelineEntry-јем, TimelineProvider-ом и WidgetConfiguration-ом. Програмеру остаје само да имплементира SwiftUI приказ за приказ података и подеси провајдера за исправан распоред ажурирања.

Испод — комплетан пример једноставног виџета за приказ тренутног курса биткоина: Provider учитава курс кроз URLSession и креира Timeline са ажурирањем сваког сата. WidgetSwiftUIView приказује курс великим фонтом и време последњег ажурирања малим фонтом.

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

Виџети екрана закључавања iOS 16+

Од iOS 16, WidgetKit је проширио подршку на Lock Screen — екран закључавања iPhone-а. Lock Screen виџети су два типа: inline (један ред текста испод сата) и rectangular (правоугаона област). За разлику од Home Screen виџета, Lock Screen виџети се ажурирају чешће — системски окидач омогућава ажурирање сваких 15–30 минута за приказ актуелних информација без откључавања телефона.

Lock Screen виџети захтевају одвојену конфигурацију кроз WidgetConfiguration са accessoryFamilies: accessoryCircular, accessoryRectangular, accessoryInline. Ове породице имају строга ограничења величине и садржаја — не подржавају слике, анимацију и прилагођене фонтове. Apple препоручује коришћење само текстуалних информација и системских икона SF Symbols за Lock Screen виџете.

• accessoryCircular — компактни округли виџет за место испод сата
• accessoryRectangular — правоугаони виџет за област изнад сата
• accessoryInline — једноредни текст испод времена, минимална величина
• Ограничења: само текст, SF Symbols, градијенти; без слика и видеа

Најбоље праксе и ограничења WidgetKit-а

При развоју виџета важно је узети у обзир ограничења WidgetKit-а. Виџети су прикази само за читање: не обрађују додирне догађаје (осим додира који отвара апликацију). Виџети не подржавају анимацију, видео, унос са тастатуре, скроловање или интерактивне елементе. Сваки виџет је статички снимак података у одређеном тренутку, а покушај додавања интерактивности довешће до одбијања апликације у App Store-у.

Најбоље праксе укључују Widget Center за принудно ажурирање, кеширање података на нивоу TimelineProvider-а за брзи одзив и коришћење placeholder-а за почетно стање. Такође је важно подржавати више величина — корисник очекује да виџет буде доступан и у small и у medium варијанти. Избегавајте приказ нетачних или застарелих података — корисник памти погрешне информације са виџета дуго времена.

Ограничења WidgetKit-а у табели