WidgetKit — ano ito, framework ng widget at SwiftUI

Ano ang WidgetKit at paano ito gumagana?

WidgetKit — framework ng Apple para sa paggawa ng mga widget na nagpapakita ng nilalaman sa mga system screen ng mga Apple device. Ang widget ay isang miniature na representasyon ng iyong app na inilalagay ng user sa home screen sa jiggle mode. Hindi tulad ng mga watchOS complication na umiral bago ang WidgetKit, pinag-isa ng bagong framework ang paggawa ng widget para sa lahat ng platform ng Apple sa pamamagitan ng isang API sa SwiftUI.

Ang prinsipyo ng pagpapatakbo ng WidgetKit ay batay sa TimelineProvider — isang bagay na lumilikha ng nakaayos na array ng TimelineEntry, kung saan ang bawat entry ay naglalaman ng Snapshot (tiyak na estado ng widget sa isang partikular na oras). Ipinapakita ng system ang mga entry nang sunud-sunod, ina-update ang widget kapag lumipat sa susunod na entry sa timeline. Sa pagitan ng mga entry, hindi tinatawag ng WidgetKit ang code ng app — ang oras ng processor ay ginugugol lamang kapag lumilikha ng bagong Timeline.

Ayon sa data ng WWDC 2024 Session „WidgetKit: What’s new”, ang karaniwang iOS user ay may 8–12 widget sa home screen, at ang pinakasikat na kategorya ay panahon, oras, kalendaryo, fitness at pananalapi. Ang WidgetKit ay kumokonsumo ng mas mababa sa 1% ng baterya bawat araw sa tipikal na paggamit dahil ang mga update ay nagaganap ayon sa iskedyul, hindi sa real-time.

Ano ang nagpapakilala sa WidgetKit mula sa lumang Today Extension

Bago ang iOS 14, ang mga widget ay umiiral lamang bilang Today View — isang panel na naa-access sa pamamagitan ng pag-swipe pakaliwa mula sa unang screen. Ang Today Extension ay may malubhang limitasyon: available lamang ang mga ito sa „Ngayon” na screen, nangangailangan ng pagbubukas ng app para i-update ang nilalaman, at may limitadong suporta sa laki. Ganap na pinalitan ng WidgetKit ang Today Extension, na nagbibigay ng mga widget sa home screen, lock screen (iOS 16+) at Mac desktop.

• Mga widget sa home screen, hindi lamang sa Today View
• Autonomous na pag-update sa pamamagitan ng TimelineProvider, nang hindi binubuksan ang app
• Tatlong paunang natukoy na laki sa halip na isa
• Smart Rotate at Smart Stack — awtomatikong pag-ikot ng widget ng system
• Nag-iisang API sa SwiftUI para sa lahat ng platform ng Apple

Arkitektura ng WidgetKit: TimelineProvider at Entry

Ang arkitektura ng WidgetKit ay batay sa tatlong pangunahing protocol: TimelineProvider, TimelineEntry at Widget. Ang TimelineEntry ay isang modelo ng data na kumakatawan sa estado ng widget sa isang partikular na oras. Ang TimelineProvider ay lumilikha ng array ng naturang mga entry (Timeline), na nagsasaad ng petsa ng activation para sa bawat isa. Widget — entry point na nag-uugnay sa provider sa SwiftUI view.

Ang pamamaraang getTimeline ay tinatawag ng system sa unang pagdaragdag ng widget at pagkatapos ay pana-panahon — karaniwang bawat 1–6 na oras depende sa uri ng provider. Ang Timeline ay maaaring maglaman ng mga entry para sa mga oras o araw nang maaga, na nagpapahintulot sa widget na gumana nang hindi tinatawagan ang code ng app sa pagitan ng mga update. Kung kailangan ng agarang pag-update ng widget (hal., nagbago ang halaga ng palitan), maaaring tawagan ng app ang WidgetCenter.shared.reloadAllTimelines() nang sapilitan.

Batayang 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

Sinusuportahan ng WidgetKit ang tatlong laki ng widget, bawat isa ay may nakapirming proporsyon. Ang Small (170×170 pt sa iPhone) ay nagpapakita ng compact na impormasyon — isang halaga, icon o maikling teksto. Ang Medium (364×170 pt) ay dalawang beses na mas malawak kaysa sa small at angkop para sa pagpapakita ng ilang halaga o mini-graph. Ang Large (364×382 pt) ay sumasakop ng halos kalahati ng screen nang patayo at nagbibigay-daan sa pagpapakita ng mga talahanayan, listahan o pinalawak na data.

Ang developer ay dapat sumuporta ng hindi bababa sa dalawang laki — inirerekomenda ng Apple ang small + medium. Ang Large widget ay kinakailangan lamang kung ang app ay may sapat na nilalaman upang punan ang naturang volume. Ang bawat laki ay tumatanggap ng sarili nitong SwiftUI view na ni-render ng WidgetKit sa system screen. Mahalaga na ang WidgetKit ay hindi sumusuporta sa custom na laki — tatlong nakapirming laki lamang, na ginagarantiyahan ang pagkakapareho ng interface.

Configuration ng laki sa pamamagitan ng 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])
    }
}

Mga uri ng configuration ng widget: Static at Intent

Nag-aalok ang WidgetKit ng dalawang uri ng configuration — StaticConfiguration at IntentConfiguration. Ang StaticConfiguration ay angkop para sa mga widget na nagpapakita ng parehong nilalaman para sa lahat ng user: halaga ng palitan, panahon, kalendaryo. Ang IntentConfiguration ay nagpapahintulot sa user na i-customize ang widget kapag idinaragdag ito sa pamamagitan ng Siri intent system — halimbawa, pumili ng partikular na lungsod para sa panahon o partikular na ticker para sa presyo ng stock.

Ang IntentConfiguration ay gumagamit ng INWidgetIntent — isang subclass ng INIntent mula sa SiriKit. Kapag nagdagdag ang user ng widget at pumili ng mga parameter (hal., lungsod), ini-save ng system ang intent na ito at ipinapasa ito sa TimelineProvider sa bawat update. Natatanggap ng provider ang intent sa getTimeline method at ginagamit ang mga parameter nito para bumuo ng nilalaman. Ang IntentConfiguration ay ang gustong paraan para sa mga personalized na widget dahil nagsasama ito sa Siri at Shortcuts.

IntentConfiguration na may pagpili ng 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)
        }
    }
}

Paggawa ng widget sa SwiftUI: hakbang-hakbang na halimbawa

Ang paggawa ng widget ay nagsisimula sa pagdaragdag ng Widget Extension Target sa Xcode: File → New → Target → Widget Extension. Awtomatikong bumubuo ang Xcode ng isang structure na may TimelineEntry, TimelineProvider at WidgetConfiguration. Ang natitira na lang sa developer ay ipatupad ang SwiftUI view para sa pagpapakita ng data at i-configure ang provider para sa tamang iskedyul ng pag-update.

Sa ibaba — kumpletong halimbawa ng isang simpleng widget para sa pagpapakita ng kasalukuyang presyo ng bitcoin: Ang Provider ay naglo-load ng presyo sa pamamagitan ng URLSession at lumilikha ng Timeline na may update bawat oras. Ang WidgetSwiftUIView ay nagpapakita ng presyo sa malaking font at oras ng huling update sa maliit na font.

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

Mga widget ng lock screen ng iOS 16+

Mula sa iOS 16, pinalawak ng WidgetKit ang suporta sa Lock Screen — lock screen ng iPhone. Ang Lock Screen widget ay may dalawang uri: inline (isang linya ng text sa ilalim ng orasan) at rectangular (parihabang lugar). Hindi tulad ng Home Screen widget, ang Lock Screen widget ay mas madalas na ina-update — pinapayagan ng system trigger ang pag-update tuwing 15–30 minuto upang magpakita ng napapanahong impormasyon nang hindi ina-unlock ang telepono.

Ang Lock Screen widget ay nangangailangan ng hiwalay na configuration sa pamamagitan ng WidgetConfiguration na may accessoryFamilies: accessoryCircular, accessoryRectangular, accessoryInline. Ang mga pamilyang ito ay may mahigpit na limitasyon sa laki at nilalaman — hindi sila sumusuporta sa mga larawan, animation at custom na font. Inirerekomenda ng Apple ang paggamit lamang ng text na impormasyon at system icon na SF Symbols para sa Lock Screen widget.

• accessoryCircular — compact na pabilog na widget para sa lugar sa ilalim ng orasan
• accessoryRectangular — parihabang widget para sa lugar sa itaas ng orasan
• accessoryInline — isang-linyang text sa ilalim ng oras, minimal na laki
• Mga limitasyon: text lamang, SF Symbols, gradient; walang larawan at video

Best practices at limitasyon ng WidgetKit

Sa pag-develop ng widget, mahalagang isaalang-alang ang mga limitasyon ng WidgetKit. Ang mga widget ay read-only na view: hindi sila nagpoproseso ng mga touch event (maliban sa pagpindot na nagbubukas ng app). Hindi sinusuportahan ng mga widget ang animation, video, input ng keyboard, pag-scroll o interactive na elemento. Ang bawat widget ay isang static na snapshot ng data sa isang partikular na oras, at ang pagtatangkang magdagdag ng interactivity ay hahantong sa pagtanggi ng app sa App Store.

Ang mga best practice ay kinabibilangan ng Widget Center para sa sapilitang pag-update, pag-cache ng data sa antas ng TimelineProvider para sa mabilis na pagtugon at paggamit ng placeholder para sa paunang estado. Mahalaga rin na suportahan ang maramihang laki — inaasahan ng user na ang widget ay available sa parehong small at medium na variant. Iwasan ang pagpapakita ng hindi tumpak o luma na data — naaalala ng user ang maling impormasyon mula sa widget nang matagal.

Mga limitasyon ng WidgetKit sa talahanayan