@capgo/capacitor-kit-widget

Ringkasan

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

• template SVG aktivitas: definisikan permukaan WidgetKit sebagai SVG, ubah frame bernama dari sentuhan, jalankan timer pause/play, ubah JSON state, dan kumpulkan 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.

Gunakan 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 async.

Demo

Alur template widget

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 dalam aplikasi yang sama. Misalnya, aplikasi olahraga dapat menggunakan Aktivitas SVG Live untuk kontrol frame/timer yang 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 Variasi SVG bernama seperti summary, timer, atau details.
• frameMutations switch, toggle, atau melalui frame setelah aksi hotspot.
• timerMutations mulai, pause, resume, toggle, reset, stop, atau ubah durasi timer.
• patches update JSON state menggunakan nilai literal, template, timestamp, increment, toggle, atau operasi hapus.
• hotspots peta area sentuhan ke identifikasi aksi.
• listTemplateEvents memungkinkan aplikasi memproses aksi asal widget kemudian.

Runtime memecahkan tempat penempatan seperti {{state.title}}, {{timers.rest.remainingText}}, dan {{meta.template.kind}} sebelum jembatan native kembali permukaan untuk rendering.

Kemampuan Jembatan Native Penuh

Session native penuh untuk widget yang mengrender UI mereka sendiri secara native:

• startWidgetSession membuat state dan metadata bersama untuk widget native code.
• updateWidgetSession Menggabungkan atau menggantikan status dan menandai sesi aktif lagi.
• stopWidgetSession Merekam status akhir dan menandai sesi berhenti.
• sendWidgetMessage Mengantre pekerjaan aplikasi ke widget atau pekerjaan widget ke aplikasi.
• acknowledgeWidgetMessages Menandai pesan sebagai diterima.
• completeWidgetMessage Menyimpan respons atau gagal untuk pekerjaan async.

Pesan-pesan 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 kegiatan template native dapat dijalankan pada perangkat saat ini.
startTemplateActivity	Simpan template SVG kegiatan dan mulai jembatan kegiatan Live Activity native.
updateTemplateActivity	Ganti definisi kegiatan, status, atau URL terbuka.
endTemplateActivity	Tutup kegiatan berjalan dan secara opsional simpan snapshot status terakhir.
performTemplateAction	Eksekusi patch deklaratif, mutasi frame, mutasi timer, dan pencatatan log event.
getTemplateActivity	Baca satu kegiatan template yang disimpan.
listTemplateActivities	Daftar semua kegiatan 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	Gabung atau ganti state sesi widget penuh-native.
stopWidgetSession	Tutup sesi widget penuh-native dan secara opsional simpan status akhir.
getWidgetSession	Baca satu sesi widget penuh-native.
listWidgetSessions	Daftar semua sesi widget penuh-native.
sendWidgetMessage	Antrum pesan antara aplikasi dan widget native code.
listWidgetMessages	Daftar pesan jembatan yang ditunggu.
acknowledgeWidgetMessages	Merk pesan jembatan sebagai diakui.
completeWidgetMessage	Mengakhiri atau gagal pesan jembatan async.
getPluginVersion	Mengembalikan tanda versi implementasi platform.

Bahagian-bahagian Native

Plugin ini juga mengirimkan bantuan 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 memuatkan sesi penuh-native dan pesan dari widget native code.
• Pengembang Android membantu template dengan perilaku penerima aksi dan jembatan widget yang sesuai.

Sumber Kebenaran

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

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 dalam Menggunakan @capgo/capacitor-widget-kit, Capgo Pengaturan CI/CD untuk alur kerja produk di Capgo Pengaturan CI/CD, Capgo Pembangunan Nativ untuk alur kerja produk di Capgo Pembangunan Nativ, Capgo Integrasi untuk alur kerja produk di Capgo Integrasi, dan Integrasi CI/CD untuk detail implementasi di Integrasi CI/CD.