@capgo/capacitor-kit-gadget

Pendahuluan

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

• Aktivitas template SVG: definisikan permukaan WidgetKit sebagai SVG, ganti frame bernama dari sentuhan, jalankan timer pause/play, ubah JSON state, dan kumpulkan acara event di aplikasi.
• Jalankan sesi widget penuh-native: simpan UI widget sepenuhnya di Swift/Kotlin/Java sementara Capacitor mengelola JSON state bersama dan pesan aplikasi ke widget atau sebaliknya.

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

Demo

Alur template widget

Pilih Mode A

Mode	Pilihan Terbaik	API Utama
Template Aktivitas SVG	Aktivitas Hidup atau permukaan widget yang menampilkan hasil output 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

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

• frames varian SVG bernama seperti summary, timer, atau details.
• frameMutations switch, toggle, or step through frames after a hotspot action.
• timerMutations switch, toggle, atau melalui frame setelah aksi hotspot.
• patches mengupdate status JSON menggunakan nilai literal, template, timestamp, inkremen, toggle, atau operasi penghapusan.
• hotspots mengatur area sentuh ke identifikasi aksi.
• listTemplateEvents memungkinkan aplikasi memproses aksi yang berasal dari widget kemudian.

Runtime memecahkan tempat penempatan seperti __CAPGO_KEEP_0__, dan __CAPGO_KEEP_1__ sebelum jembatan native kembali menampilkan permukaan untuk rendering. {{state.title}}, {{timers.rest.remainingText}}Kemampuan Jembatan Native Penuh {{meta.template.kind}} Bab berjudul “Kemampuan Jembatan Native Penuh”

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

menggabungkan atau mengganti status dan menandai sesi aktif lagi.

• startWidgetSession creates shared state and metadata for native widget code.
• updateWidgetSession mengupdate status JSON menggunakan nilai literal, template, timestamp, inkremen, toggle, atau operasi penghapusan.
• stopWidgetSession mengatur area sentuh ke identifikasi aksi.
• sendWidgetMessage mengantarkan aplikasi ke widget atau sebaliknya.
• acknowledgeWidgetMessages menandai pesan sebagai diterima.
• completeWidgetMessage menyimpan tanggapan atau gagal untuk pekerjaan async.

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

Publik API

Metode	Deskripsi
areActivitiesSupported	Periksa apakah jembatan kegiatan template asli dapat dijalankan pada perangkat saat ini.
startTemplateActivity	Simpan template SVG kegiatan dan mulai jembatan kegiatan Live Activity asli.
updateTemplateActivity	Ganti definisi kegiatan, keadaan, atau URL terbuka.
endTemplateActivity	Selesaikan kegiatan yang berjalan dan secara opsional simpan snapshot keadaan terakhir.
performTemplateAction	Eksekusi patch deklaratif, mutasi frame, mutasi timer, dan pencatatan event.
getTemplateActivity	Baca satu aktivitas template yang disimpan.
listTemplateActivities	Tampilkan semua aktivitas template yang disimpan.
listTemplateEvents	Baca event aksi yang diemiti oleh aksi template.
acknowledgeTemplateEvents	Tandai event template sebagai diproses.
startWidgetSession	Mulai sesi widget penuh-native yang didukung oleh JSON state bersama.
updateWidgetSession	Gabungkan atau gantikan state sesi widget penuh-native.
stopWidgetSession	Hentikan sesi widget penuh-native dan simpan state akhir secara opsional.
getWidgetSession	Baca satu sesi widget penuh-native.
listWidgetSessions	Tampilkan semua sesi widget penuh-native.
sendWidgetMessage	Antrikan pesan antara aplikasi dan widget native code.
listWidgetMessages	Tampilkan pesan jembatan yang antri.
acknowledgeWidgetMessages	Merk pesan jembatan sebagai diakui.
completeWidgetMessage	Selesaikan atau gagal pesan jembatan async.
getPluginVersion	Kembalikan tanda versi implementasi platform.

Penggalan Asli

Plugin ini juga mengirimkan bantuan asli native untuk target widget:

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

Sumber Kebenaran

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

Teruskan dari @capgo/capacitor-kit-gadget

Jika Anda menggunakan @capgo/capacitor-kit-gadget untuk merencanakan otomatisasi CI/CD, hubungkannya dengan Menggunakan @capgo/capacitor-kit-gadget untuk kemampuan asli dalam Menggunakan @capgo/capacitor-kit-gadget, Capgo CI/CD untuk alur kerja produk dalam Capgo CI/CD, Pembangunan Nativ Capgo untuk alur kerja produk di Pembangunan Nativ Capgo Integrasi Capgo untuk alur kerja produk di Integrasi Capgo Integrasi, dan Integrasi CI/CD untuk detail implementasi di Integrasi CI/CD.