@capgo/capacitor-widget-kit

Ringkasan

@capgo/capacitor-widget-kit gives a Capacitor app two ways to drive widgets and Live Activities:

• SVG template aktivitas: definisikan permukaan Kit Widget sebagai SVG, ubah frame bernama 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 bersama dan pesan aplikasi-ke-widget atau widget-ke-aplikasi.

Pilih template SVG ketika widget dapat di-render dari string SVG yang terpecahkan. Gunakan sesi widget penuh-native ketika widget memerlukan UI native yang kustom tetapi masih harus memulai, menghentikan, sinkronisasi state, atau meminta aplikasi untuk menyelesaikan pekerjaan asinkron.

Demo

Alur template widget

Pilih Mode

Mode	Terbaik untuk	API Utama
Aktivitas SVG template	Aktivitas hidup atau permukaan widget yang menampilkan hasil SVG	startTemplateActivity, performTemplateAction, listTemplateEvents
Sesi widget penuh-native	Widget yang diterjemahkan secara native yang memerlukan state bersama dan pekerjaan asinkron	startWidgetSession, updateWidgetSession, sendWidgetMessage

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

Kemampuan Template SVG

Template SVG termasuk bagian-bagian yang diperlukan untuk permukaan widget interaktif:

• frames bernama SVG variasi seperti summary, timer, atau details.
• frameMutations switch, toggle, atau melalui frame setelah aksi hotspot.
• timerMutations mulai, pause, resume, toggle, reset, stop, atau mengubah durasi timer.
• patches mengupdate status JSON menggunakan nilai literal, template, timestamp, inkremen, toggle, atau operasi hapus.
• hotspots menghubungkan area sentuh ke identifikasi aksi.
• listTemplateEvents mengizinkan aplikasi memproses aksi asal widget kemudian.

Runtime menyelesaikan tempat-tempat seperti {{state.title}}, {{timers.rest.remainingText}}dan {{meta.template.kind}} sebelum jembatan asli kembali menyediakan permukaan untuk rendering.

Kemampuan Jembatan Penuh-Native

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

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

Pesan-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 aktivitas jembatan template native dapat dijalankan pada perangkat saat ini.
startTemplateActivity	Simpan template SVG aktivitas dan mulai jembatan Live Activity native.
updateTemplateActivity	Ganti definisi aktivitas, keadaan, atau URL terbuka.
endTemplateActivity	Akhirkan aktivitas yang berjalan dan opsionalnya simpan snapshot keadaan terakhir.
performTemplateAction	Jalankan patch deklaratif, mutasi frame, mutasi timer, dan pencatatan event.
getTemplateActivity	Baca satu template aktivitas yang disimpan.
listTemplateActivities	Tampilkan semua template aktivitas yang disimpan.
listTemplateEvents	Baca event aksi yang dikeluarkan oleh aksi template.
acknowledgeTemplateEvents	Merkkan event template sebagai diproses.
startWidgetSession	Mulai sesi widget penuh-nasional yang didukung oleh JSON state bersama.
updateWidgetSession	Menggabungkan atau mengganti state sesi widget penuh-nasional.
stopWidgetSession	Hentikan sesi widget penuh-nasional dan opsionalnya simpan state akhir.
getWidgetSession	Baca satu sesi widget penuh-nasional.
listWidgetSessions	Tampilkan setiap sesi widget penuh-nasional.
sendWidgetMessage	Antrian pesan antara aplikasi dan widget native code.
listWidgetMessages	Tampilkan pesan antrian bridge.
acknowledgeWidgetMessages	Merk pesan bridge sebagai diakui.
completeWidgetMessage	Lengkapkan atau gagalkan pesan bridge async.
getPluginVersion	Kembalikan tanda versi implementasi platform.

Bagian-bagian Native

Paket ini juga menyediakan bantuan asli untuk target widget:

• CapgoTemplateWidgetBridge mengatasi permukaan template SVG ke svg, frameId, hotspots, dan metadata.
• CapgoTemplateActionIntent menghubungkan tombol widget iOS interaktif ke aksi template.
• CapgoNativeWidgetBridge memuat sesi dan pesan penuh-asli dari widget code.
• Bantuan template Android menyediakan perilaku penerima aksi dan jembatan widget yang sesuai.

Sumber Kebenaran

Referensi API disinkronkan dari src/definitions.ts dalam repositori paket.

Teruskan dari @capgo/capacitor-widget-kit

Jika Anda menggunakan @capgo/capacitor-widget-kit untuk merencanakan otomatisasi CI/CD, hubungkannya dengan Menggunakan @capgo/capacitor-widget-kit untuk kemampuan asli di Menggunakan @capgo/capacitor-widget-kit, Capgo CI/CD untuk alur kerja produk di Capgo CI/CD, Capgo Pembangunan Asli untuk alur kerja produk di Capgo Pembangunan Asli, Capgo Integrasi for the product workflow in Capgo Integrations, and Integrasi CI/CD untuk detail implementasi di Integrasi CI/CD