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.

Timeline метод 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 View, которое 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 View для отображения данных и настроить провайдера для корректного расписания обновлений.

Ниже — полный пример простого виджета для отображения текущего курса биткоина: 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, градиенты; без изображений и видео

Best practices и ограничения WidgetKit

При разработке виджетов важно учитывать ограничения WidgetKit. Виджеты — это read-only представления: они не обрабатывают touch-события (кроме тапа, который открывает приложение). Виджеты не поддерживают анимацию, видео, клавиатурный ввод, скроллинг или интерактивные элементы. Каждый виджет — это статичный снимок данных на определённый момент времени, и попытка добавить интерактивность приведёт к отклонению приложения в App Store.

Лучшие практики включают Widget Center для принудительного обновления, кэширование данных на уровне TimelineProvider для быстрого отклика и использование placeholder для первоначального состояния. Также важно поддерживать несколько размеров — пользователь ожидает, что виджет будет доступен как в small, так и в medium варианте. Религиозно избегайте отображения неточных или устаревших данных — пользователь запоминает неправильную информацию с виджета надолго.

Ограничения WidgetKit в таблице