WidgetKit — bu nədir, vidjet freymvorku və SwiftUI

WidgetKit nədir və necə işləyir?

WidgetKit — Apple cihazlarının sistem ekranlarında məzmun göstərən vidjetlər yaratmaq üçün Apple freymvorku. Vidjet — istifadəçinin ’silkələmə’ rejimində (jiggle mode) ana ekranda yerləşdirdiyi proqramınızın miniatür təqdimatıdır. WidgetKit-dən əvvəl mövcud olan watchOS komplikasiyalarından fərqli olaraq, yeni freymvork SwiftUI-də vahid API vasitəsilə bütün Apple platformaları üçün vidjet yaradılmasını birləşdirdi.

WidgetKit-in işləmə prinsipi TimelineProvider-ə əsaslanır — hər bir yazının müəyyən bir zamanda vidjetin konkret vəziyyətini (Snapshot) ehtiva etdiyi sıralanmış TimelineEntry massivi yaradan obyekt. Sistem yazıları ardıcıl olaraq göstərir və zaman xəttində növbəti yazıya keçid zamanı vidjeti yeniləyir. Yazılar arasında WidgetKit proqram kodunu çağırmır — prosessor vaxtı yalnız yeni Timeline yaradılarkən sərf olunur.

WWDC 2024 Session „WidgetKit: What’s new” məlumatlarına görə, orta iOS istifadəçisinin ana ekranında 8–12 vidjet var və ən populyar kateqoriyalar hava, saat, təqvim, fitness və maliyyədir. WidgetKit yeniləmələr cədvəl üzrə baş verdiyi və real vaxtda olmadığı üçün tipik istifadədə gündə batareyanın 1%-dən azını istehlak edir.

WidgetKit köhnə Today Extension-dan nə ilə fərqlənir

iOS 14-dən əvvəl vidjetlər yalnız Today View şəklində mövcud idi — ilk ekrandan sola sürüşdürmə ilə əldə edilə bilən panel. Today Extension ciddi məhdudiyyətlərə malik idi: onlar yalnız „Bugün” ekranında mövcud idi, məzmunu yeniləmək üçün proqramın açılmasını tələb edirdi və məhdud ölçü dəstəyinə malik idi. WidgetKit Today Extension-ı tamamilə əvəz edərək ana ekranda, blok ekranında (iOS 16+) və Mac iş masasında vidjetlər təmin etdi.

• Yalnız Today View-də deyil, ana ekranda vidjetlər
• Proqramı açmadan TimelineProvider vasitəsilə müstəqil yeniləmə
• Bir əvəzinə üç əvvəlcədən təyin olunmuş ölçü
• Smart Rotate və Smart Stack — sistem tərəfindən vidjetlərin avtomatik rotasiyası
• Bütün Apple platformaları üçün SwiftUI-də vahid API

WidgetKit arxitekturası: TimelineProvider və Entry

WidgetKit arxitekturası üç əsas protokola əsaslanır: TimelineProvider, TimelineEntry və Widget. TimelineEntry müəyyən bir zamanda vidjetin vəziyyətini təmsil edən məlumat modelidir. TimelineProvider hər biri üçün aktivasiya tarixi göstərən belə yazıların massivini (Timeline) yaradır. Widget — provayderi SwiftUI görünüşünə bağlayan giriş nöqtəsidir.

getTimeline metodu sistem tərəfindən vidjet ilk dəfə əlavə edildikdə və sonra dövri olaraq — adətən provayderin növündən asılı olaraq hər 1–6 saatdan bir çağırılır. Timeline saatlar və ya günlər qabaq üçün yazılar ehtiva edə bilər, bu da vidjetin yeniləmələr arasında proqram kodunu çağırmadan işləməsinə imkan verir. Təcili yeniləmə lazım olduqda (məsələn, valyuta məzənnəsi dəyişdi), proqram WidgetCenter.shared.reloadAllTimelines() çağıra bilər.

Əsas 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 hər biri sabit nisbətlərə malik üç vidjet ölçüsünü dəstəkləyir. Small (iPhone-da 170×170 pt) yığcam məlumat göstərir — tək dəyər, ikona və ya qısa mətn. Medium (364×170 pt) small-dan iki dəfə genişdir və bir neçə dəyər və ya mini-qrafik göstərmək üçün uyğundur. Large (364×382 pt) ekranın şaquli olaraq təxminən yarısını tutur və cədvəllər, siyahılar və ya genişləndirilmiş məlumatlar göstərməyə imkan verir.

Proqramçı ən azı iki ölçünü dəstəkləməlidir — Apple small + medium tövsiyə edir. Large vidjet yalnız proqramın belə bir həcmi doldurmaq üçün kifayət qədər məzmunu olduqda tələb olunur. Hər ölçü öz SwiftUI görünüşünü alır, WidgetKit onu sistem ekranında render edir. WidgetKit-ın xüsusi ölçüləri dəstükləmədiyini qeyd etmək vacibdir — yalnız üç sabit ölçü, bu da interfeysin vəhdliyini təmin edir.

WidgetConfiguration ilə ölçülərin konfiqurasiyası

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

Vidjet konfiqurasiya növləri: Static və Intent

WidgetKit iki konfiqurasiya növü təklif edir — StaticConfiguration və IntentConfiguration. StaticConfiguration bütün istifadəçilər üçün eyni məzmunu göstərən vidjetlər üçün uyğundur: valyuta məzənnələri, hava, təqvim. IntentConfiguration istifadəçiyə Siri intent sistemi vasitəsilə vidjet əlavə edərkən onu fərdiləşdirməyə imkan verir — məsələn, hava üçün konkret şəhər və ya səhm kursu üçün konkret ticker seçmək.

IntentConfiguration INWidgetIntent istifadə edir — SiriKit-dən INIntent-in alt sinfi. İstifadəçi vidjet əlavə edib parametrləri seçdikdə (məsələn, şəhər), sistem bu intenti saxlayır və hər yeniləmədə TimelineProvider-ə ötürür. Provayder intenti getTimeline metodunda alır və məzmun yaratmaq üçün onun parametrlərindən istifadə edir. IntentConfiguration fərdiləşdirilmiş vidjetlər üçün üstünlük verilən üsuldur, çünki Siri və Shortcuts ilə inteqrasiya olunur.

Parametr seçimi ilə 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-də vidjet yaratmaq: addım-addım nümunə

Vidjet yaratmaq Xcode-da Widget Extension Target əlavə etməklə başlayır: File → New → Target → Widget Extension. Xcode avtomatik olaraq TimelineEntry, TimelineProvider və WidgetConfiguration ilə struktur yaradır. Proqramçıya yalnız məlumat göstərmək üçün SwiftUI görünüşünü tətbiq etmək və düzgün yeniləmə cədvəli üçün provayderi konfiqurasiya etmək qalır.

Aşağıda — Bitcoin-in cari məzənnəsini göstərmək üçün sadə vidjetin tam nümunəsi: Provider URLSession vasitəsilə məzənnəni yükləyir və hər saat yenilənən Timeline yaradır. WidgetSwiftUIView məzənnəni böyük şriftlə və son yeniləmə vaxtını kiçik şriftlə göstərir.

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+ blok ekranı vidjetləri

iOS 16-dan etibarən WidgetKit Lock Screen — iPhone blok ekranını dəstəkləyir. Lock Screen vidjetləri iki növdə olur: inline (saatın altında bir sətir mətn) və rectangular (dördbucaqlı sahə). Home Screen vidjetlərindən fərqli olaraq, Lock Screen vidjetləri daha tez-tez yenilənir — sistem tetikleyicisi telefonu açmadan aktual məlumat göstərmək üçün onları hər 15–30 dəqiqədə bir yeniləməyə imkan verir.

Lock Screen vidjetləri WidgetConfiguration vasitəsilə accessoryFamilies ilə ayrıca konfiqurasiya tələb edir: accessoryCircular, accessoryRectangular, accessoryInline. Bu ailələrin ölçü və məzmun baxımından ciddi məhdudiyyətləri var — onlar şəkilləri, animasiyanı və xüsusi şriftləri dəstəkləmir. Apple Lock Screen vidjetləri üçün yalnız mətn məlumatı və sistem SF Symbols ikonlarından istifadə etməyi tövsiyə edir.

• accessoryCircular — saatın altında yer üçün yığcam dairəvi vidjet
• accessoryRectangular — saatın üstündəki sahə üçün dördbucaqlı vidjet
• accessoryInline — vaxtın altında bir sətir mətn, minimal ölçü
• Məhdudiyyətlər: yalnız mətn, SF Symbols, gradientlər; şəkil və video yoxdur

WidgetKit üçün best practices və məhdudiyyətlər

Vidjetlərin hazırlanmasında WidgetKit məhdudiyyətlərini nəzərə almaq vacibdir. Vidjetlər yalnız oxumaq üçün görünüşlərdir: onlar toxunma hadisələrini emal etmir (proqramı açan toxunma istisna olmaqla). Vidjetlər animasiya, video, klaviatura daxiletməsi, sürüşdürmə və ya interaktiv elementləri dəstəkləmir. Hər vidjet müəyyən bir zamanda məlumatın statik şəklidir və interaktivlik əlavə etmək cəhdi App Store-da proqramın rədd edilməsinə səbəb olacaq.

Ən yaxşı təcrübələr Widget Center-dən məcburi yeniləmə üçün istifadə, sürətli cavab üçün TimelineProvider səviyyəsində məlumatların keşlənməsi və ilkin vəziyyət üçün placeholder istifadəsini əhatə edir. Həmçinin bir neçə ölçünü dəstəkləmək vacibdir — istifadəçi vidjetin həm small, həm də medium variantında mövcud olmasını gözləyir. Qeyri-dəqiq və ya köhnəlmiş məlumatların göstərilməsindən qaçının — istifadəçi vidjetdən yanlış məlumatı uzun müddət xatırlayır.

WidgetKit məhdudiyyətləri cədvəldə