@capgo/capacitor-widget-kit

Panoramica

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

• Attività di template 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.
• Sessioni di widget native complete: mantiene l'interfaccia utente del widget completamente in Swift/Kotlin/Java mentre Capacitor gestisce lo stato JSON condiviso e i messaggi app-to-widget o widget-to-app.

Usa i template SVG quando il tuo widget può essere reso da stringhe SVG risolte. Usa le sessioni native complete quando il widget richiede un'interfaccia utente nativa personalizzata ma deve ancora avviarsi, fermarsi, sincronizzare lo stato o chiedere all'app di completare il lavoro asincrono.

Demo

Flusso del modello del widget

Scegli un Modalità

Modalità	Migliore per	API principali
Attività SVG del modello	Attività live o superfici di widget che si rendono da uscita SVG	startTemplateActivity, performTemplateAction, listTemplateEvents
Sessione del widget nativo a tutto campo	Widget nativi renderizzati che richiedono stato condiviso e job asincroni	startWidgetSession, updateWidgetSession, sendWidgetMessage

Entrambi i modi possono convivere nello stesso app. Ad esempio, un'applicazione di allenamento può utilizzare un'attività SVG Live per controlli di frame/timer veloci e una sessione widget nativa completa per un widget di schermo principale con un layout nativo più ricco.

Capacità del modello SVG

I modelli SVG includono le parti necessarie per superfici widget interattive:

• frames varianti di SVG denominate con un nome come summary, timero details.
• frameMutations passare da una schermata all'altra dopo un'azione su un hotspot.
• timerMutations avviare, sospensione, riprendere, abilitare/disabilitare, resettare o fermare il timer o modificare la sua durata.
• patches aggiornare lo stato JSON utilizzando valori letterali, modelli, timestamp, incrementi, abilitazioni o operazioni di cancellazione.
• hotspots mappare aree di tocco a identificatori di azione.
• listTemplateEvents consente all'applicazione di elaborare azioni originate dal 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.

Capacità del Ponte Nativo Completo

Il ponte nativo completo è per widget che rendono la propria UI nativamente:

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

Il messaggi sono idempotenti dopo la completamento: riprovando un messaggio completato o fallito restituisce il risultato esistente invece di sovrascriverlo.

Pubblico API

Metodo	Descrizione
areActivitiesSupported	Verifica se il ponte di attività di template nativo può essere eseguito sul dispositivo corrente.
startTemplateActivity	Mantieni un template di attività SVG e avvia il ponte di attività nativo Live.
updateTemplateActivity	Sostituisci la definizione dell'attività, lo stato o l'URL aperto.
endTemplateActivity	Termina un'attività in esecuzione e, facoltativamente, mantieni un'ultima snapshot di stato.
performTemplateAction	Esegui patch dichiarative, mutazioni di frame, mutazioni di timer e registrazione degli eventi.
getTemplateActivity	Leggi un'attività di template archiviata.
listTemplateActivities	Elenco tutte le attività di template archiviate.
listTemplateEvents	Leggi gli eventi di azione emessi dalle azioni di template.
acknowledgeTemplateEvents	Segnala eventi di template come elaborati.
startWidgetSession	Avvia una sessione di widget nativo a piena capacità supportata da uno stato JSON condiviso.
updateWidgetSession	Unisci o sostituisci uno stato di sessione di widget nativo a piena capacità.
stopWidgetSession	Interrompi una sessione di widget nativo a piena capacità e opzionalmente persisti lo stato finale.
getWidgetSession	Leggi una sessione di widget nativo a piena capacità.
listWidgetSessions	Elencare tutte le sessioni di widget nativo a piena capacità.
sendWidgetMessage	Inoltra un messaggio tra l'app e il widget nativo code.
listWidgetMessages	Elencare i messaggi di ponte in coda.
acknowledgeWidgetMessages	Segnala i messaggi di ponte come riconosciuti.
completeWidgetMessage	Concludi o falli un messaggio di ponte asincrono.
getPluginVersion	Restituisci il marchio di versione dell'implementazione di piattaforma.

Pezzi nativi

Il plugin fornisce anche aiuti nativi per i target widget:

• CapgoTemplateWidgetBridge risolve una superficie di template SVG in svg, frameId, hotspots, e metadati.
• CapgoTemplateActionIntent connette pulsanti widget interattivi iOS a azioni di template.
• CapgoNativeWidgetBridge carica sessioni e messaggi full-native da widget code.
• 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.

Continua da @capgo/capacitor-widget-kit

Se stai utilizzando @capgo/capacitor-kit di widget per pianificare l'automazione CI/CD, connettilo con Utilizzando @capgo/capacitor-kit di widget per la capacità nativa in Utilizzando @capgo/capacitor-kit di widget, Capgo Automazione CI/CD per il flusso di lavoro del prodotto in Capgo Automazione CI/CD, Capgo Costruzioni native per il flusso di lavoro del prodotto in Capgo Costruzioni native, Capgo Integrazioni for the product workflow in Capgo Integrations, and Integrazione CI/CD per i dettagli di implementazione nell'integrazione CI/CD