@capgo/capacitor-kit di widget

Panoramica

@capgo/capacitor-widget-kit Fornisce a un'app Capacitor due modi per gestire i widget e le attività in tempo reale:

• Il widget di attività SVG: definisci le superfici del kit di widget come SVG, passa tra le finestre denominate dai tocchi, esegui i timer di pausa/riavvio, modifica lo stato JSON e raccogli gli eventi di azione nell'app.
• Il widget di sessione nativa completa: mantiene l'interfaccia utente del widget completamente in Swift/Kotlin/Java mentre Capacitor possiede lo stato JSON condiviso e i messaggi app-to-widget o widget-to-app.

Usa template SVG quando il widget può essere reso da stringhe SVG risolte. Usa sessioni native complete quando il widget ha bisogno di un'interfaccia UI nativa personalizzata, ma deve ancora iniziare, fermarsi, sincronizzare lo stato o chiedere all'app di completare il lavoro asincrono.

Scegli un Modalità

Migliore per	API principali	Attività SVG template
Attività Live o superfici widget che renderizzano da output SVG	Sessione widget nativa completa	startTemplateActivity, performTemplateAction, listTemplateEvents
Widget nativi renderizzati che richiedono stato condiviso e lavori asincroni	Entrambe le modalità possono esistere nello stesso app. Ad esempio, un'app di allenamento può utilizzare un'attività Live SVG per controlli di frame/timer veloci e una sessione widget nativa completa per un widget di schermo principale con una disposizione nativa più ricca.	startWidgetSession, updateWidgetSession, sendWidgetMessage

Capacità del template SVG

__CAPGO_KEEP_0__

I template SVG includono le parti necessarie per le superfici di widget interattive:

• frames nome varianti SVG denominate summary, timer, o details.
• frameMutations passare da una finestra di frame ad un'altra dopo un'azione hotspot.
• timerMutations iniziare, pausare, riprendere, abilitare/disabilitare, resettare, fermare o modificare la durata del timer.
• patches aggiornare lo stato JSON utilizzando valori letterali, template, timestamp, incrementi, toggle o operazioni di cancellazione.
• hotspots mappare aree di tocco a identificatori di azione.
• listTemplateEvents consente all'applicazione di elaborare azioni originate dai widget in un momento successivo.

Il runtime risolve i placeholder come {{state.title}}, {{timers.rest.remainingText}}, e {{meta.template.kind}} prima che il ponte nativo restituisca una superficie per la rendering.

Funzionalità di ponte nativa completa

Le sessioni native sono per widget che rendono la propria UI nativamente:

• startWidgetSession crea uno stato e metadati condivisi per il widget nativo code.
• updateWidgetSession fonde o sostituisce lo stato e segnala la sessione attiva nuovamente.
• stopWidgetSession registra uno stato finale e segnala la sessione fermata.
• sendWidgetMessage inserisce lavoro app-to-widget o widget-to-app in coda.
• acknowledgeWidgetMessages segna i messaggi come ricevuti.
• completeWidgetMessage memorizza una risposta o un fallimento per i lavori asincroni.

I messaggi sono idempotenti dopo completamento: riprovando un messaggio completato o fallito restituisce il risultato esistente anziché sovrascriverlo.

Pubblico API

Metodo	Descrizione
areActivitiesSupported	Verifica se il ponte di attività di template nativo può eseguire il codice sul dispositivo corrente.
startTemplateActivity	Mantieni un template di attività SVG e avvia il ponte di attività Live nativo.
updateTemplateActivity	Sostituisci la definizione dell'attività, lo stato o l'URL aperto.
endTemplateActivity	Termina un'attività in esecuzione e, facoltativamente, mantieni uno snapshot dello stato finale.
performTemplateAction	Esegui patch dichiarative, mutazioni di frame, mutazioni di timer e registrazione degli eventi.
getTemplateActivity	Leggi un template di attività memorizzato.
listTemplateActivities	Elencare tutte le attività di template memorizzate.
listTemplateEvents	Leggi gli eventi di azione emessi dalle azioni di template.
acknowledgeTemplateEvents	Segna gli eventi di template come elaborati.
startWidgetSession	Avvia una sessione di widget nativo completa supportata da uno stato JSON condiviso.
updateWidgetSession	Unisci o sostituisci lo stato di sessione di un widget nativo completo.
stopWidgetSession	Interrompi una sessione di widget nativo completo e conserva eventualmente lo stato finale.
getWidgetSession	Leggi una sessione di widget nativo completa.
listWidgetSessions	Elenco tutte le sessioni di widget nativo.
sendWidgetMessage	Inserisci un messaggio nella coda tra l'app e il widget nativo code.
listWidgetMessages	Elenco i messaggi nella coda del bridge.
acknowledgeWidgetMessages	Segna i messaggi del bridge come riconosciuti.
completeWidgetMessage	Completa o fallisce un messaggio asincrono del bridge.
getPluginVersion	Restituisci il marchio di versione dell'implementazione del platform.

Pezzi nativi

Il plugin fornisce anche aiuti nativi per i target di widget:

• CapgoTemplateWidgetBridge risolve una superficie di template SVG in svg, frameId, hotspots, e metadati.
• CapgoTemplateActionIntent connette pulsanti widget iOS interattivi a azioni di template.
• CapgoNativeWidgetBridge carica sessioni e messaggi full-native da widget nativo code.
• Gli helper di template Android forniscono comportamento di ricezione di azione e ponte di widget corrispondente.

Fonte di Verità

La API di riferimento è sincronizzata da src/definitions.ts nella repository del plugin.