@capgo/capacitor-widget-kit

Ikhtisar

Bangun surface WidgetKit dan Live Activity dari Capacitor dengan frame SVG, timer, action hotspots, atau sinkronisasi state widget full-native

Mulai dengan areActivitiesSupported() dan metode inti lainnya yang tercantum di bawah ini.

Dukungan platform

Platform	Dukungan	Catatan
iOS	Ya	Native
Android	Ya	Native
Web	Tidak	Lindungi dengan Capacitor.getPlatform()

Siri, Shortcuts, dan App Intents

Widget Kit adalah tidak jembatan Siri atau Shortcuts. Ini memang mencakup WidgetKit, template Live Activities ActivityKit, dan kontrol iOS interaktif melalui LiveActivityIntent tipe bundled (CapgoTemplateActionIntent, CompleteSetIntent) yang memperbarui state template tersimpan dan menambahkan ke log event (listTemplateEvents / acknowledgeTemplateEvents).

Ini memang tidak registrasi frasa shortcut kustom, AppShortcutsProvider, katalog entitas JavaScript, item Spotlight, atau skema aplikasi Apple. Gunakan @capgo/capacitor-app-intents untuk itu. Untuk perbandingan lengkap dengan tools seperti expo-app-intents, lihat Siri, Shortcuts, dan widget.

Demo

Alur template widget

Pilih Mode

Mode	Terbaik untuk	API Utama
Aktivitas template SVG	Live Activities atau permukaan widget yang dirender dari output SVG	startTemplateActivity, performTemplateAction, listTemplateEvents
Sesi widget full-native	Widget render-native yang butuh shared state dan async jobs	startWidgetSession, updateWidgetSession, sendWidgetMessage

Kedua mode bisa berjalan di aplikasi yang sama. Contohnya, aplikasi workout bisa pakai SVG Live Activity untuk kontrol timer/frame yang cepat dan sesi widget full-native untuk widget home-screen dengan layout native yang lebih kaya.

Kemampuan Template SVG

Template SVG mencakup komponen yang dibutuhkan untuk permukaan widget interaktif:

• frames menyimpan varian SVG bernama seperti summary, timer, atau details.
• frameMutations switch, toggle, atau berpindah frame setelah aksi hotspot.
• timerMutations start, pause, resume, toggle, reset, stop, atau ubah durasi timer.
• patches update state JSON menggunakan nilai literal, template, timestamp, increment, toggle, atau operasi unset.
• hotspots memetakan area tap ke identifier aksi.
• listTemplateEvents memungkinkan app memproses aksi dari widget di kemudian hari.

Runtime akan menyelesaikan placeholder seperti {{state.title}}, {{timers.rest.remainingText}}, dan {{meta.template.kind}} sebelum native bridge mengembalikan surface untuk rendering.

Kemampuan Full-Native Bridge Lengkap

Sesi full-native ditujukan untuk widget yang merender UI-nya sendiri secara native:

• startWidgetSession membuat shared state dan metadata untuk widget native code.
• updateWidgetSession menggabungkan atau mengganti state dan menandai sesi aktif kembali.
• stopWidgetSession mencatat state akhir dan menandai sesi berhenti.
• sendWidgetMessage mengantrekan pekerjaan app-to-widget atau widget-to-app.
• acknowledgeWidgetMessages menandai pesan sebagai sudah diterima.
• completeWidgetMessage menyimpan respons atau kegagalan untuk job async.

Pesan bersifat idempotent setelah selesai: mencoba ulang pesan yang sudah selesai atau gagal akan mengembalikan hasil yang ada, bukan menimpanya.

API Publik

Metode	Deskripsi
areActivitiesSupported	Cek apakah bridge activity template native bisa berjalan di perangkat saat ini.
startTemplateActivity	Simpan activity template SVG dan jalankan bridge Live Activity native.
updateTemplateActivity	Ganti definisi activity, state, atau URL yang dibuka.
endTemplateActivity	Akhiri activity yang sedang berjalan dan simpan snapshot state terakhir secara opsional.
performTemplateAction	Eksekusi declarative patch, mutasi frame, mutasi timer, dan logging event.
getTemplateActivity	Baca satu activity template yang tersimpan.
listTemplateActivities	Daftar semua aktivitas template yang tersimpan.
listTemplateEvents	Baca action event yang dihasilkan oleh action template.
acknowledgeTemplateEvents	Tandai event template sebagai sudah diproses.
startWidgetSession	Mulai sesi widget full-native dengan state JSON bersama.
updateWidgetSession	Merge atau ganti state sesi widget full-native.
stopWidgetSession	Hentikan sesi widget full-native dan simpan state akhir secara opsional.
getWidgetSession	Baca satu sesi widget full-native.
listWidgetSessions	List semua sesi widget full-native.
sendWidgetMessage	Antrekan pesan antara aplikasi dan code widget native.
listWidgetMessages	List pesan bridge yang sedang diantrekan.
acknowledgeWidgetMessages	Tandai pesan bridge sebagai sudah diakui.
completeWidgetMessage	Selesaikan atau gagalkan pesan bridge async.
getPluginVersion	Kembalikan marker versi implementasi platform.

Native Pieces

Plugin ini juga menyertakan native helper untuk target widget:

• CapgoTemplateWidgetBridge merender permukaan template SVG menjadi svg, frameId, hotspots, dan metadata.
• CapgoTemplateActionIntent menghubungkan tombol widget iOS interaktif ke aksi template.
• CapgoNativeWidgetBridge memuat sesi full-native dan pesan dari native widget code.
• Android template helper menyediakan action receiver dan perilaku widget bridge yang sesuai.

Sumber Kebenaran

Referensi API disinkronkan dari src/definitions.ts di repositori plugin.

Lanjutkan dari @capgo/capacitor-widget-kit

Jika Anda menggunakan @capgo/capacitor-widget-kit untuk merencanakan otomatisasi CI/CD, hubungkan dengan Menggunakan @capgo/capacitor-widget-kit untuk kapabilitas native saat menggunakan @capgo/capacitor-widget-kit, CI/CD Capgo untuk workflow produk di Capgo CI/CD, Capgo Native Build untuk workflow produk di Capgo Native Builds, Integrasi Capgo untuk workflow produk di Capgo Integrations, dan Integrasi CI/CD untuk detail implementasi di CI/CD Integration.