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 — например да избере конкретен град за времето или конкретен тикер за цената на акция.

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 в таблица