@capgo/capacitor-widget-kit

Ringkasan

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

• SVG template aktivitas: definisikan permukaan Kit Widget sebagai SVG, switch frame yang dinamai dari sentuhan, jalankan timer pause/play, ubah JSON state, dan kumpulkan acara event 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 widget ke aplikasi.

Pilih template SVG ketika widget Anda 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 state, atau meminta aplikasi untuk menyelesaikan pekerjaan asinkron.

Pameran

Alur Template Widget

Pilih Mode

Mode	Terbaik untuk	API Utama
Aktivitas Template SVG	Aktivitas Langsung atau permukaan widget yang menampilkan hasil output SVG	startTemplateActivity, performTemplateAction, listTemplateEvents
Sesi Widget Penuh-Native	Widget yang dirender secara native yang memerlukan state bersama dan pekerjaan asinkron	startWidgetSession, updateWidgetSession, sendWidgetMessage

Kedua mode dapat hidup bersama dalam 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 mencakup bagian-bagian yang diperlukan untuk permukaan widget interaktif:

• frames menggunakan variasi SVG bernama seperti summary, timer, atau details.
• frameMutations mengubah, toggle, atau melalui frame setelah aksi hotspot.
• timerMutations memulai, menunda, melanjutkan, toggle, mengatur ulang, menghentikan, atau mengubah durasi timer.
• patches mengupdate nilai JSON menggunakan nilai literal, template, timestamp, peningkatan, toggle, atau operasi hapus.
• hotspots menghubungkan area sentuh ke identifikasi aksi.
• listTemplateEvents memungkinkan 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 sendiri secara native:

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

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

Publik API

Methode	Deskripsi
areActivitiesSupported	Periksa apakah jembatan kegiatan template native dapat dijalankan pada perangkat saat ini.
startTemplateActivity	Simpan template SVG kegiatan dan mulai jembatan Live Activity native.
updateTemplateActivity	Ganti definisi kegiatan, status, atau URL terbuka.
endTemplateActivity	Selesaikan kegiatan yang berjalan dan simpan snapshot status terakhir secara opsional.
performTemplateAction	Eksekusi patch deklaratif, mutasi frame, mutasi timer, dan logging event.
getTemplateActivity	Baca satu kegiatan template yang disimpan.
listTemplateActivities	Tampilkan semua kegiatan template yang disimpan.
listTemplateEvents	Baca event aksi yang diemiti oleh aksi template.
acknowledgeTemplateEvents	Merkkan event template sebagai diproses.
startWidgetSession	Mulai sesi widget penuh-bangun asli yang didukung oleh JSON bersama.
updateWidgetSession	Menggabungkan atau mengganti status sesi widget penuh-bangun asli.
stopWidgetSession	Hentikan sesi widget penuh-bangun asli dan secara opsional simpan status akhir.
getWidgetSession	Baca satu sesi widget penuh-bangun asli.
listWidgetSessions	Tampilkan setiap sesi widget penuh-bangun asli.
sendWidgetMessage	Antrian pesan antara aplikasi dan widget native code.
listWidgetMessages	Tampilkan pesan antrian jembatan.
acknowledgeWidgetMessages	Merkkan pesan jembatan sebagai diakui.
completeWidgetMessage	Lengkapkan atau gagalkan pesan jembatan async.
getPluginVersion	Kembalikan tanda versi implementasi platform.

Bahagian-bahagian Asli

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 Native Builds untuk alur kerja produk di Capgo Native Builds, Capgo Integrasi for the product workflow in Capgo Integrations, and Integrasi CI/CD untuk detail implementasi di Integrasi CI/CD.