WidgetKit — apa itu, framework widget dan SwiftUI

Apa itu WidgetKit dan bagaimana cara kerjanya?

WidgetKit — framework Apple untuk membuat widget yang menampilkan konten di layar sistem perangkat Apple. Widget adalah representasi miniatur dari aplikasi Anda yang ditempatkan pengguna di layar utama dalam mode goyangan (jiggle mode). Tidak seperti komplikasi watchOS yang sudah ada sebelum WidgetKit, framework baru ini menyatukan pembuatan widget untuk semua platform Apple melalui API tunggal di SwiftUI.

Prinsip kerja WidgetKit didasarkan pada TimelineProvider — objek yang membuat array terurut dari TimelineEntry, di mana setiap entri berisi Snapshot (status spesifik widget pada waktu tertentu). Sistem menampilkan entri secara berurutan, memperbarui widget saat beralih ke entri berikutnya pada garis waktu. Di antara entri, WidgetKit tidak memanggil kode aplikasi — waktu prosesor hanya dihabiskan saat membuat Timeline baru.

Menurut data WWDC 2024 Session „WidgetKit: What’s new”, rata-rata pengguna iOS memiliki 8–12 widget di layar utama, dan kategori terpopuler adalah cuaca, waktu, kalender, kebugaran, dan keuangan. WidgetKit mengonsumsi kurang dari 1% baterai per hari dalam penggunaan tipikal karena pembaruan terjadi sesuai jadwal, bukan secara real-time.

Apa yang membedakan WidgetKit dari Today Extension lama

Sebelum iOS 14, widget hanya ada dalam bentuk Today View — panel yang dapat diakses dengan menggeser ke kiri dari layar pertama. Today Extension memiliki keterbatasan serius: hanya tersedia di layar „Hari Ini”, memerlukan pembukaan aplikasi untuk memperbarui konten, dan memiliki dukungan ukuran yang terbatas. WidgetKit sepenuhnya menggantikan Today Extension, menyediakan widget di layar utama, layar kunci (iOS 16+), dan desktop Mac.

• Widget di layar utama, tidak hanya di Today View
• Pembaruan mandiri melalui TimelineProvider, tanpa membuka aplikasi
• Tiga ukuran yang telah ditentukan sebelumnya, bukan satu
• Smart Rotate dan Smart Stack — rotasi otomatis widget oleh sistem
• API tunggal di SwiftUI untuk semua platform Apple

Arsitektur WidgetKit: TimelineProvider dan Entry

Arsitektur WidgetKit didasarkan pada tiga protokol kunci: TimelineProvider, TimelineEntry dan Widget. TimelineEntry adalah model data yang mewakili status widget pada waktu tertentu. TimelineProvider membuat array dari entri-entri tersebut (Timeline), dengan menentukan tanggal aktivasi untuk masing-masing. Widget — titik masuk yang menghubungkan penyedia dengan tampilan SwiftUI.

Metode getTimeline dipanggil oleh sistem saat pertama kali widget ditambahkan dan kemudian secara periodik — biasanya setiap 1–6 jam tergantung pada jenis penyedia. Timeline dapat berisi entri untuk jam atau hari ke depan, memungkinkan widget bekerja tanpa memanggil kode aplikasi di antara pembaruan. Jika widget perlu segera diperbarui (misalnya, kurs mata uang berubah), aplikasi dapat memanggil WidgetCenter.shared.reloadAllTimelines() secara paksa.

TimelineProvider Dasar

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 mendukung tiga ukuran widget, masing-masing dengan proporsi tetap. Small (170×170 pt di iPhone) menampilkan informasi kompak — satu nilai, ikon, atau teks pendek. Medium (364×170 pt) dua kali lebih lebar dari small dan cocok untuk menampilkan beberapa nilai atau grafik mini. Large (364×382 pt) menempati hampir setengah layar secara vertikal dan memungkinkan menampilkan tabel, daftar, atau data yang diperluas.

Pengembang harus mendukung setidaknya dua ukuran — Apple merekomendasikan small + medium. Widget Large hanya diperlukan jika aplikasi memiliki cukup konten untuk mengisi volume tersebut. Setiap ukuran mendapatkan tampilan SwiftUI sendiri yang dirender WidgetKit di layar sistem. Penting bahwa WidgetKit tidak mendukung ukuran kustom — hanya tiga ukuran tetap, yang menjamin keseragaman antarmuka.

Konfigurasi ukuran melalui 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])
    }
}

Jenis konfigurasi widget: Static dan Intent

WidgetKit menawarkan dua jenis konfigurasi — StaticConfiguration dan IntentConfiguration. StaticConfiguration cocok untuk widget yang menampilkan konten yang sama untuk semua pengguna: kurs mata uang, cuaca, kalender. IntentConfiguration memungkinkan pengguna menyesuaikan widget saat menambahkannya melalui sistem intent Siri — misalnya, memilih kota tertentu untuk cuaca atau ticker tertentu untuk harga saham.

IntentConfiguration menggunakan INWidgetIntent — subkelas dari INIntent dari SiriKit. Saat pengguna menambahkan widget dan memilih parameter (misalnya, kota), sistem menyimpan intent ini dan meneruskannya ke TimelineProvider pada setiap pembaruan. Penyedia menerima intent dalam metode getTimeline dan menggunakan parameternya untuk menghasilkan konten. IntentConfiguration adalah metode yang lebih disukai untuk widget yang dipersonalisasi karena terintegrasi dengan Siri dan Shortcuts.

IntentConfiguration dengan pemilihan parameter

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

Membuat widget di SwiftUI: contoh langkah demi langkah

Pembuatan widget dimulai dengan menambahkan Widget Extension Target di Xcode: File → New → Target → Widget Extension. Xcode secara otomatis menghasilkan struktur dengan TimelineEntry, TimelineProvider, dan WidgetConfiguration. Pengembang hanya perlu mengimplementasikan tampilan SwiftUI untuk menampilkan data dan mengonfigurasi penyedia untuk jadwal pembaruan yang benar.

Di bawah ini — contoh lengkap widget sederhana untuk menampilkan harga bitcoin saat ini: Provider memuat harga melalui URLSession dan membuat Timeline dengan pembaruan setiap jam. WidgetSwiftUIView menampilkan harga dengan font besar dan waktu pembaruan terakhir dengan font kecil.

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

Widget layar kunci iOS 16+

Mulai iOS 16, WidgetKit memperluas dukungan ke Lock Screen — layar kunci iPhone. Widget Lock Screen terdiri dari dua jenis: inline (satu baris teks di bawah jam) dan rectangular (area persegi panjang). Tidak seperti widget Home Screen, widget Lock Screen lebih sering diperbarui — pemicu sistem memungkinkan pembaruan setiap 15–30 menit untuk menampilkan informasi terkini tanpa membuka kunci ponsel.

Widget Lock Screen memerlukan konfigurasi terpisah melalui WidgetConfiguration dengan accessoryFamilies: accessoryCircular, accessoryRectangular, accessoryInline. Keluarga ini memiliki batasan ketat pada ukuran dan konten — mereka tidak mendukung gambar, animasi, dan font kustom. Apple merekomendasikan hanya menggunakan informasi teks dan ikon sistem SF Symbols untuk widget Lock Screen.

• accessoryCircular — widget bundar kompak untuk tempat di bawah jam
• accessoryRectangular — widget persegi panjang untuk area di atas jam
• accessoryInline — teks satu baris di bawah waktu, ukuran minimal
• Batasan: hanya teks, SF Symbols, gradien; tanpa gambar dan video

Best practices dan keterbatasan WidgetKit

Saat mengembangkan widget, penting untuk mempertimbangkan keterbatasan WidgetKit. Widget adalah tampilan hanya-baca: mereka tidak memproses peristiwa sentuh (kecuali sentuhan yang membuka aplikasi). Widget tidak mendukung animasi, video, input keyboard, pengguliran, atau elemen interaktif. Setiap widget adalah snapshot statis data pada waktu tertentu, dan upaya menambahkan interaktivitas akan menyebabkan penolakan aplikasi di App Store.

Praktik terbaik mencakup Widget Center untuk pembaruan paksa, penyimpanan cache data di tingkat TimelineProvider untuk respons cepat, dan penggunaan placeholder untuk status awal. Juga penting untuk mendukung beberapa ukuran — pengguna mengharapkan widget tersedia dalam varian small maupun medium. Hindari menampilkan data yang tidak akurat atau usang — pengguna mengingat informasi yang salah dari widget untuk waktu yang lama.

Keterbatasan WidgetKit dalam tabel