@capgo/capacitor-kit-widget

Ringkasan

@capgo/capacitor-widget-kit memberikan aplikasi Capacitor dua cara untuk menggerakkan 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 kumpulkan event aksi di aplikasi.
• Sesi widget penuh-native: simpan UI widget sepenuhnya di Swift/Kotlin/Java sementara Capacitor mengontrol JSON state yang dibagikan dan pesan aplikasi ke widget atau sebaliknya.

Gunakan template SVG ketika widget Anda dapat dirender dari string SVG yang telah terpecahkan. Gunakan sesi full-native ketika widget memerlukan antarmuka native kustom 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
Kegiatan template SVG	Aktivitas Live atau permukaan widget yang mengrender dari output SVG	startTemplateActivity, performTemplateAction, listTemplateEvents
Session Widget Penuh-Nasional	Komponen native yang memerlukan status bersama dan pekerjaan async	startWidgetSession, updateWidgetSession, sendWidgetMessage

Kedua Mode Dapat Berada di Aplikasi yang Sama. Misalnya, Aplikasi Olahraga dapat Menggunakan Aktivitas Layar Aktif SVG untuk Kontrol Frame/Timer yang Cepat dan Session Widget Penuh-Nasional untuk Widget Layar Utama dengan Tampilan Nasional yang Lebih Kaya.

Kemampuan Template SVG

Template SVG termasuk Bagian-Bagian yang Diperlukan untuk Permukaan Widget yang Interaktif:

• frames Variasi SVG yang Dinamai seperti summary, timer, atau details.
• frameMutations Switch, Toggle, atau Langkah Melalui Frame Setelah Aksi Hotspot.
• timerMutations Mulai, Berhenti, Tambah, Tambahkan, Reset, Berhenti, atau Ubah Durasi Timer.
• patches Ubah Status JSON Menggunakan Nilai Literal, Template, Waktu Tanggal, Inkremen, Toggle, atau Operasi Unset.
• hotspots Peta Area Sentuh ke Identifikasi Aksi.
• listTemplateEvents biarkan aplikasi memproses aksi asal widget kemudian.

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

Kemampuan Jembatan Penuh-Native

Sesi penuh-native adalah untuk widget yang menampilkan UI 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 aplikasi-ke-widget atau widget-ke-aplikasi.
• acknowledgeWidgetMessages menandai pesan sebagai diterima.
• completeWidgetMessage menyimpan tanggapan atau gagal untuk pekerjaan async.

Setelah selesai, pesan-pesan tersebut idempoten: mencoba ulang pesan yang sudah selesai atau gagal akan mengembalikan hasil yang sudah 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, keadaan, atau URL terbuka.
endTemplateActivity	Selesai kegiatan yang berjalan dan simpan snapshot keadaan terakhir secara opsional.
performTemplateAction	Eksekusi patch deklaratif, perubahan frame, perubahan timer, dan pencatatan event.
getTemplateActivity	Baca kegiatan template yang disimpan.
listTemplateActivities	Daftar semua aktivitas template yang disimpan.
listTemplateEvents	Membaca event aksi yang diemitsi oleh aksi template.
acknowledgeTemplateEvents	Merkirkan event template sebagai diproses.
startWidgetSession	Mulai sebuah sesi widget penuh-native yang didukung oleh JSON state bersama.
updateWidgetSession	Menggabungkan atau mengganti state sesi widget penuh-native.
stopWidgetSession	Hentikan sebuah sesi widget penuh-native dan secara opsional menyimpan state final.
getWidgetSession	Membaca satu sesi widget penuh-native.
listWidgetSessions	Daftar semua sesi widget penuh-native.
sendWidgetMessage	Antrian pesan antara aplikasi dan widget native code.
listWidgetMessages	Daftar pesan bridge yang antri.
acknowledgeWidgetMessages	Merkirkan pesan bridge sebagai diakui.
completeWidgetMessage	Mengakhiri atau gagal pesan bridge async.
getPluginVersion	Mengembalikan tanda versi implementasi platform.

Bagian-bagian Asli

Plugin ini juga mengirimkan bantuan asli 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 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 di repository plugin.

Teruskan dari @capgo/capacitor-widget-kit

Jika Anda menggunakan @capgo/capacitor-kit-gadget 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, Buat Capgo Build Natively untuk alur kerja produk di Capgo Native Builds, Integrasi Capgo untuk alur kerja produk di Capgo Integrasi, dan Integrasi CI/CD untuk detail implementasi di Integrasi CI/CD.