@capgo/capacitor-widget-kit

Riepilogo

@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 superfici WidgetKit come SVG, passa da frame denominati a tocchi, esegui timer di pausa/riavvio, muta stato JSON e raccogli eventi di azione nell'app.
• sessioni di widget native complete: mantieni 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 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 template del widget

Scegli un Modo

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

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 un layout nativo più ricco.

Capacità di template SVG

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

• frames varianti di SVG denominate summary, timero switch, toggle, o passare attraverso le frame dopo un'azione hotspot. details.
• frameMutations iniziare, sospensione, ripresa, toggle, reset, fermare, o modificare la durata del timer.
• timerMutations aggiornare lo stato JSON utilizzando valori letterali, template, timestamp, incrementi, toggle o operazioni di cancellazione.
• patches mappare aree di tocco a identificatori di azione.
• hotspots il processo dell'app consente azioni originate dai widget in un momento successivo.
• listTemplateEvents Il runtime risolve i placeholder come

, e {{state.title}}, {{timers.rest.remainingText}}prima che il ponte nativo restituisca una superficie per la rendering. {{meta.template.kind}} Capacità del Ponte Nativo Completo

Sottosezione intitolata “Capacità del Ponte Nativo Completo”

aggiornare lo stato JSON utilizzando valori letterali, template, timestamp, incrementi, toggle o operazioni di cancellazione.

• startWidgetSession crea uno stato e metadati condivisi per il widget nativo code.
• updateWidgetSession unisce o sostituisce lo stato e segnala la sessione attiva nuovamente.
• stopWidgetSession registra uno stato finale e segnala 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.

I messaggi sono idempotenti dopo la loro completamento: riprovando un messaggio completato o fallito si ottiene il risultato esistente al posto di sovrascriverlo.

Pubblico API

Metodo	Descrizione
areActivitiesSupported	Verifica se il ponte di attività del template nativo può eseguirsi sul dispositivo corrente.
startTemplateActivity	Mantieni un'attività di template SVG e avvia il ponte di attività nativa Live.
updateTemplateActivity	Sostituisci la definizione, lo stato o l'URL aperto dell'attività.
endTemplateActivity	Termina un'attività in esecuzione e, facoltativamente, persisti un ultimo 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	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 nativa completa supportata da uno stato JSON condiviso.
updateWidgetSession	Unisci o sostituisci uno stato di sessione di widget nativa completa.
stopWidgetSession	Interrompi una sessione di widget nativa e, facoltativamente, persisti lo stato finale.
getWidgetSession	Leggi una sessione di widget nativa completa.
listWidgetSessions	Elencare ogni sessione di widget nativo completo.
sendWidgetMessage	Inserire un messaggio tra l'app e il widget nativo code.
listWidgetMessages	Elencare i messaggi di ponte in coda.
acknowledgeWidgetMessages	Segnalare i messaggi di ponte come riconosciuti.
completeWidgetMessage	Concludere o fallire un messaggio di ponte asincrono.
getPluginVersion	Restituire il marchio di versione dell'implementazione della piattaforma.

Pezzi nativi

Il plugin fornisce anche aiuti nativi per i target di widget: risolve una superficie di template SVG in

• CapgoTemplateWidgetBridge e metadati. svg, frameId, hotspotsconnette i pulsanti di widget iOS interattivi a azioni di template.
• CapgoTemplateActionIntent risolve un template di superficie SVG in
• CapgoNativeWidgetBridge carica sessioni e messaggi full-native dal widget nativo code.
• Gli aiuti di template per Android forniscono comportamento di ricezione di azione e ponte widget.

Fonte di Verità

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

Continua da @capgo/capacitor-kit-di-widget

Se stai utilizzando @capgo/capacitor-kit-di-widget per pianificare l'automazione di CI/CD, connettilo con Utilizzando @capgo/capacitor-kit-di-widget per la capacità nativa in Utilizzo di @capgo/capacitor-kit di widget, Capgo CI/CD per il flusso di lavoro del prodotto in Capgo CI/CD, Capgo Costruzioni native per il flusso di lavoro del prodotto in Capgo Costruzioni native, Capgo Integrazioni per il flusso di lavoro del prodotto in Capgo Integrazioni, e Integrazione CI/CD per la dettaglio di implementazione in Integrazione CI/CD.