WidgetKit — nedir, widget framework'ü ve SwiftUI

WidgetKit nedir ve nasıl çalışır?

WidgetKit, Apple cihazlarının sistem ekranlarında içerik görüntüleyen widget'lar oluşturmak için bir Apple framework'üdür. Widget, kullanıcının jiggle modunda ana ekrana yerleştirdiği uygulamanızın minyatür bir temsilidir. WidgetKit'ten önce var olan watchOS komplikasyonlarının aksine, yeni framework, tek bir SwiftUI API'si aracılığıyla tüm Apple platformları için widget oluşturmayı birleştirmiştir.

WidgetKit'in çalışma prensibi TimelineProvider'a dayanır — sıralı bir TimelineEntry dizisi oluşturan bir nesne; her giriş bir Snapshot (belirli bir zamanda widget'ın belirli bir durumu) içerir. Sistem, girişleri sırayla görüntüler ve zaman çizelgesinde bir sonraki girişe geçerken widget'ı günceller. Girişler arasında WidgetKit, uygulama kodunu çağırmaz — CPU süresi yalnızca yeni bir Timeline oluşturulurken harcanır.

WWDC 2024 Oturumu “WidgetKit: What’s new”'a göre, ortalama bir iOS kullanıcısının ana ekranında 8–12 widget bulunur ve en popüler kategoriler hava durumu, saat, takvim, fitness ve finanstr. WidgetKit, gerçek zamanlı güncellemeler yerine programlı güncellemeler sayesinde tipik kullanımda günde %1'den az pil tüketir.

WidgetKit'i eski Today Extensions'dan ayıran nedir?

iOS 14'ten önce widget'lar yalnızca Today View olarak mevcuttu — ilk ekrandan sola kaydırarak erişilebilen bir panel. Today Extensions'ın ciddi sınırlamaları vardı: yalnızca “Bugün” ekranında kullanılabilirlerdi, içeriği güncellemek için uygulamayı açmayı gerektiriyorlardı ve sınırlı boyut desteğine sahiptiler. WidgetKit, Today Extensions'ı tamamen değiştirerek ana ekran, kilit ekranı (iOS 16+) ve Mac masaüstünde widget'lar sağlamıştır.

• Yalnızca Today View'da değil, ana ekranda widget'lar
• Uygulamayı açmadan TimelineProvider aracılığıyla otonom güncelleme
• Bir yerine üç önceden tanımlanmış boyut
• Smart Rotate ve Smart Stack — sistem tarafından otomatik widget döndürme
• Tüm Apple platformları için birleşik SwiftUI API

WidgetKit Mimarisi: TimelineProvider ve Entry

WidgetKit mimarisi üç temel protokol üzerine kurulmuştur: TimelineProvider, TimelineEntry ve Widget. TimelineEntry, widget'ın belirli bir andaki durumunu temsil eden bir veri modelidir. TimelineProvider, bu tür girişlerin bir dizisini (Timeline) oluşturur ve her biri için etkinleştirme tarihini belirtir. Widget, sağlayıcıyı SwiftUI görünümüne bağlayan giriş noktasıdır.

Timeline yöntemi getTimeline, widget ilk eklendiğinde sistem tarafından çağrılır ve daha sonra periyodik olarak — genellikle sağlayıcı türüne bağlı olarak her 1–6 saatte bir — çağrılır. Bir Timeline, saatler veya günler ilerisi için girişler içerebilir ve widget'ın güncellemeler arasında uygulama kodunu çağırmadan çalışmasına olanak tanır. Acil bir widget güncellemesi gerekiyorsa (örneğin, döviz kuru değişti), uygulama WidgetCenter.shared.reloadAllTimelines()'ı zorla çağırabilir.

Temel 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, her biri sabit oranlara sahip üç widget boyutunu destekler. Small (iPhone'da 170×170 pt) kompakt bilgileri görüntüler — tek bir değer, simge veya kısa metin. Medium (364×170 pt), small'dan iki kat daha geniştir ve değer çiftlerini veya mini grafikleri görüntülemek için uygundur. Large (364×382 pt) dikey olarak ekranın neredeyse yarısını kaplar ve tabloları, listeleri veya genişletilmiş verileri görüntülemeye olanak tanır.

Geliştirici en az iki boyutu desteklemelidir — Apple small + medium önermektedir. Large widget, yalnızca uygulamanın bu hacmi dolduracak yeterli içeriğe sahip olması durumunda gereklidir. Her boyut, WidgetKit'in sistem ekranında render ettiği kendi SwiftUI View'ını alır. Önemli olan, WidgetKit'in özel boyutları desteklememesidir — yalnızca üç sabit boyut, arayüz tutarlılığını garanti eder.

WidgetConfiguration ile Boyut Yapılandırması

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 Yapılandırma Türleri: Static ve Intent

WidgetKit iki yapılandırma türü sunar — StaticConfiguration ve IntentConfiguration. StaticConfiguration, tüm kullanıcılar için aynı içeriği görüntüleyen widget'lar için uygundur: döviz kurları, hava durumu, takvim. IntentConfiguration, kullanıcının Siri intent sistemi aracılığıyla widget eklerken onu özelleştirmesine olanak tanır — örneğin, hava durumu için belirli bir şehir veya hisse senedi fiyatı için belirli bir ticker seçmek.

IntentConfiguration, INWidgetIntent kullanır — SiriKit'ten INIntent'in bir alt sınıfı. Kullanıcı bir widget ekleyip parametreler seçtiğinde (örneğin, şehir), sistem bu intent'i kaydeder ve her güncellemede TimelineProvider'a iletir. Sağlayıcı, getTimeline yönteminde intent'i alır ve içeriği oluşturmak için parametrelerini kullanır. IntentConfiguration, Siri ve Shortcuts ile entegre olduğu için kişiselleştirilmiş widget'lar için tercih edilen yaklaşımdır.

Parametre Seçimiyle 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'da Widget Oluşturma: Adım Adım Örnek

Widget oluşturma, Xcode'da Widget Extension Target eklemekle başlar: File → New → Target → Widget Extension. Xcode, TimelineEntry, TimelineProvider ve WidgetConfiguration ile otomatik olarak bir yapı oluşturur. Geliştiricinin yalnızca verileri görüntülemek için SwiftUI View'ı uygulaması ve doğru güncelleme programı için sağlayıcıyı yapılandırması yeterlidir.

Aşağıda, mevcut Bitcoin fiyatını görüntüleyen basit bir widget'ın tam örneği verilmiştir: Provider, URLSession aracılığıyla kuru yükler ve saatlik güncellemelerle bir Timeline oluşturur. WidgetSwiftUIView, kuru büyük yazı tipinde ve son güncelleme zamanını küçük yazı tipinde gösterir.

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+ Kilit Ekranı Widget'ları

iOS 16 ile WidgetKit, Kilit Ekranı — iPhone kilit ekranı — desteğini genişletti. Kilit ekranı widget'ları iki türdedir: inline (saatin altında tek satır metin) ve rectangular (dikdörtgen alan). Ana ekran widget'larının aksine, kilit ekranı widget'ları daha sık güncellenir — sistem tetikleyicisi, telefonun kilidini açmadan güncel bilgileri görüntülemek için her 15–30 dakikada bir güncellemeye izin verir.

Kilit ekranı widget'ları, accessoryFamilies ile WidgetConfiguration aracılığıyla ayrı yapılandırma gerektirir: accessoryCircular, accessoryRectangular, accessoryInline. Bu ailelerin katı boyut ve içerik sınırlamaları vardır — resimleri, animasyonları veya özel yazı tiplerini desteklemezler. Apple, kilit ekranı widget'ları için yalnızca metin bilgisi ve SF Symbols sistem simgelerinin kullanılmasını önerir.

• accessoryCircular — saatin altındaki alan için kompakt dairesel widget
• accessoryRectangular — saatin üstündeki alan için dikdörtgen widget
• accessoryInline — saatin altında tek satır metin, minimum boyut
• Sınırlamalar: yalnızca metin, SF Symbols, gradyanlar; resim veya video yok

WidgetKit En İyi Uygulamaları ve Sınırlamaları

Widget'lar geliştirirken WidgetKit'in sınırlamalarını dikkate almak önemlidir. Widget'lar salt okunur görünümlerdir: dokunma olaylarını işlemezler (uygulamayı açan bir dokunma hariç). Widget'lar animasyonu, videoyu, klavye girişini, kaydırmayı veya etkileşimli öğeleri desteklemez. Her widget, belirli bir andaki verilerin statik bir anlık görüntüsüdür ve etkileşim eklemeye çalışmak, uygulamanın App Store'dan reddedilmesine neden olur.

En iyi uygulamalar arasında zorunlu güncellemeler için Widget Center kullanımı, hızlı yanıt için TimelineProvider düzeyinde veri önbelleğe alma ve başlangıç durumu için placeholder kullanımı yer alır. Birden çok boyutu desteklemek de önemlidir — kullanıcılar widget'ın hem small hem de medium varyantında mevcut olmasını bekler. Yanlış veya güncel olmayan verileri görüntülemekten kesinlikle kaçının — kullanıcılar widget'lardan gelen yanlış bilgileri uzun süre hatırlar.

WidgetKit Sınırlamaları Tablosu