@capgo/capacitor-kit di widget

Panoramica

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

• Attività di modello SVG: definisci superfici di WidgetKit come SVG, passa da frame denominati a tap, esegui timer di pausa/riavvio, muta lo stato JSON e raccogli eventi di azione nell'app.
• Sessioni di widget nativo completo: mantiene l'interfaccia utente del widget completamente in Swift/Kotlin/Java mentre Capacitor possiede uno stato JSON condiviso e messaggi app-to-widget o widget-to-app.

Usa modelli SVG quando il tuo widget può essere reso da stringhe SVG risolte. Usa sessioni di widget nativo completo quando il widget ha bisogno di un'interfaccia utente nativa personalizzata ma deve ancora iniziare, fermare, sincronizzare lo stato o chiedere all'app di completare lavoro asincrono.

Scegli un Modalità

Modalità	Migliore per	API principali
Attività di template SVG	Attività Live o superfici widget che rendono da output SVG	startTemplateActivity, performTemplateAction, listTemplateEvents
Sessione widget nativa completa	Widget nativi renderizzati che richiedono stato condiviso e lavori asincroni	startWidgetSession, updateWidgetSession, sendWidgetMessage

Entrambe le modalità possono convivere nello stesso app. Ad esempio, un'app di allenamento può utilizzare un'attività Live SVG per controlli di timer veloci e una sessione widget nativa completa per un widget di schermo di casa con un layout nativo più ricco.

Capacità di template SVG

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

• frames mantengono varianti SVG denominate come summary, timer, o details.
• frameMutations passare attraverso le frame dopo un'azione hotspot.
• timerMutations inizia, pausa, riprendi, attiva/desattiva, resetta, fermati o modifica la durata del timer.
• patches aggiorna lo stato JSON utilizzando valori letterali, template, timestamp, incrementi, toggle o operazioni di annullamento.
• hotspots mappa le aree di tocco alle 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à del Ponte Nativo Completo

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 di nuovo.
• stopWidgetSession registra uno stato finale e segnala la sessione fermata.
• sendWidgetMessage inserisce lavoro app-to-widget o widget-to-app in coda.
• acknowledgeWidgetMessages segnala 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 al posto di 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 stato di snapshot finale.
performTemplateAction	Esegui patch dichiarative, mutazioni di frame, mutazioni di timer e registrazione degli eventi.
getTemplateActivity	Leggi un template di attività archiviato.
listTemplateActivities	Elencare tutte le attività di template archiviate.
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 a piena capacità supportata da uno stato condiviso in formato JSON.
updateWidgetSession	Unisci o sostituisci uno stato di sessione di widget nativo a piena capacità.
stopWidgetSession	Interrompi una sessione di widget nativo completo e persisti eventualmente lo stato finale.
getWidgetSession	Leggi una sessione di widget nativo completo.
listWidgetSessions	Elenco tutte le sessioni di widget nativo completo.
sendWidgetMessage	Incolca un messaggio tra l'app e il widget nativo code.
listWidgetMessages	Elenco i messaggi di ponte in coda.
acknowledgeWidgetMessages	Segna i messaggi di ponte come riconosciuti.
completeWidgetMessage	Completa o fallisce un messaggio di ponte asincrono.
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 i pulsanti widget iOS interattivi a azioni di template.
• CapgoNativeWidgetBridge carica sessioni e messaggi full-native da widget nativo code.
• Gli aiuti di template Android forniscono comportamento di ricezione azione e ponte widget corrispondente.

Fonte Di Verità

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