@capgo/capacitor-kit-widget

Ringkasan

@capgo/capacitor-widget-kit Memberikan aplikasi Capacitor dua cara untuk mengemudikan widget dan Aktivitas Hidup:

• Aktivitas template SVG: definisikan permukaan Kit Widget sebagai SVG, ubah frame yang ditetapkan dari sentuhan, jalankan timer pause/play, ubah JSON state, dan koleksi event aksi di aplikasi.
• Sesi widget penuh-native: simpan UI widget sepenuhnya di Swift/Kotlin/Java sementara Capacitor mengelola JSON state yang dibagikan dan pesan aplikasi ke widget atau sebaliknya.

Gunakan template SVG ketika widget dapat dirender dari string SVG yang terpecahkan. Gunakan sesi widget penuh-native ketika widget memerlukan UI native yang disesuaikan tetapi masih harus memulai, menghentikan, sinkronisasi status, atau meminta aplikasi untuk menyelesaikan pekerjaan asinkron.

Pilih Mode

Mode	Terbaik untuk	API Utama
Aktivitas Template SVG	Aktivitas Hidup atau permukaan widget yang menampilkan hasil SVG	startTemplateActivity, performTemplateAction, listTemplateEvents
Sesi Widget Penuh-Native	Widget yang diterjemahkan secara native yang memerlukan status bersama dan pekerjaan async	startWidgetSession, updateWidgetSession, sendWidgetMessage

Kedua mode dapat hidup di aplikasi yang sama. Misalnya, aplikasi olahraga dapat menggunakan Aktivitas Hidup SVG untuk kontrol frame/timer cepat dan sesi widget penuh-native untuk widget layar utama dengan tata letak native yang lebih kaya.

Kemampuan Template SVG

Templat SVG mencakup bagian-bagian yang diperlukan untuk permukaan widget interaktif:

• frames mengandung variasi SVG bernama seperti summary, timer, atau details.
• frameMutations memungkinkan pengguna beralih, mengubah, atau melalui frame setelah aksi hotspot.
• timerMutations memungkinkan pengguna memulai, menunda, melanjutkan, mengubah, mengatur ulang, menghentikan, atau mengubah durasi timer.
• patches mengupdate keadaan JSON menggunakan nilai literal, template, tanggal, peningkatan, toggle, atau operasi penghapusan.
• hotspots menghubungkan area sentuhan ke identifikasi aksi.
• listTemplateEvents memungkinkan aplikasi memproses aksi yang berasal dari widget kemudian.

Pemecah kode runtime menggantikan tempat-tempat seperti {{state.title}}, {{timers.rest.remainingText}}, dan {{meta.template.kind}} sebelum jembatan asli kembali permukaan untuk rendering.

Kemampuan Jembatan Asli Penuh

Sesi penuh-native adalah untuk widget yang mengrender UI mereka sendiri secara native:

• startWidgetSession membuat keadaan bersama dan metadata untuk widget native code.
• updateWidgetSession menggabungkan atau mengganti keadaan dan menandai sesi aktif lagi.
• stopWidgetSession merekam keadaan akhir dan menandai sesi berhenti.
• sendWidgetMessage mengantre pekerjaan app-to-widget atau widget-to-app.
• acknowledgeWidgetMessages menandai pesan sebagai diterima.
• completeWidgetMessage menyimpan respons atau gagal untuk pekerjaan async.

Pesan adalah idempoten setelah selesai: mencoba ulang pesan yang selesai atau gagal akan mengembalikan hasil yang ada bukan menggantinya.

Publik API

Metode	Deskripsi
areActivitiesSupported	Periksa apakah jembatan aktivitas template asli dapat dijalankan pada perangkat saat ini.
startTemplateActivity	Simpan template SVG aktivitas dan mulai jembatan Live Activity asli.
updateTemplateActivity	Ganti definisi aktivitas, status, atau buka URL.
endTemplateActivity	Akhirkan aktivitas berjalan dan opsional simpan snapshot status terakhir.
performTemplateAction	Eksekusi patch deklaratif, mutasi frame, mutasi timer, dan logging event.
getTemplateActivity	Baca satu template aktivitas yang disimpan.
listTemplateActivities	Tampilkan semua template aktivitas yang disimpan.
listTemplateEvents	Baca event aksi yang diemiti oleh aksi template.
acknowledgeTemplateEvents	Tandai event template sebagai diproses.
startWidgetSession	Mulai sesi widget penuh-asli yang didukung oleh JSON state bersama.
updateWidgetSession	Gabungkan atau ganti state sesi widget penuh-asli.
stopWidgetSession	Hentikan sesi widget penuh-nativ dan opsionalnya simpan keadaan akhir.
getWidgetSession	Baca satu sesi widget penuh-nativ.
listWidgetSessions	Daftar semua sesi widget penuh-nativ.
sendWidgetMessage	Antrian pesan antara aplikasi dan widget natif code.
listWidgetMessages	Daftar pesan jembatan yang diantre.
acknowledgeWidgetMessages	Tandai pesan jembatan sebagai terkonfirmasi.
completeWidgetMessage	Selesaikan atau gagalkan pesan jembatan async.
getPluginVersion	Kembalikan tanda versi implementasi platform.

Bagian-bagian Natif

Plugin ini juga mengirimkan bantuan natif untuk target widget:

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

Sumber Kebenaran

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