@capgo/capacitor-kit di widget

Kit di widget e attività in tempo reale per le app Capacitor, con modelli guidati da SVG o sincronizzazione dello stato del widget nativo completo.

Inizia GitHub

Panoramica

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

Template di attività 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 widget può essere reso da stringhe SVG risolte. Usa sessioni native complete quando il widget richiede un'interfaccia utente nativa personalizzata ma deve ancora iniziare, fermare, sincronizzare lo stato o chiedere all'app di completare il lavoro asincrono.

Demo

Scegli Un Modalità

Modalità	La migliore 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 convivere 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 home-screen con un layout nativo più ricco.

Capacità di template SVG

Le matrici SVG includono le parti necessarie per le superfici di widget interattive:

frames nomevano varianti SVG come summary, timer, o details.
frameMutations passare attraverso le frame dopo un'azione hotspot.
timerMutations avviare, sospensione, riprendere, abilitare/disabilitare, resettare, fermare o modificare la durata del timer.
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 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 segna la sessione attiva di nuovo.
stopWidgetSession registra uno stato finale e segna la sessione fermata.
sendWidgetMessage inserisce lavoro app-to-widget o widget-to-app in coda.
acknowledgeWidgetMessages segna 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`	Persisti 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 persisti optionalmente uno snapshot dello stato finale.
`performTemplateAction`	Esegui patch dichiarative, mutazioni di frame, mutazioni di timer e registrazione degli eventi.
`getTemplateActivity`	Lega un template di attività memorizzato.
`listTemplateActivities`	Elenco tutti i template di attività memorizzati.
`listTemplateEvents`	Lega gli eventi delle azioni 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 stato JSON condiviso.
`updateWidgetSession`	Unisci o sostituisci lo stato di sessione di widget nativo a piena capacità.
`stopWidgetSession`	Interrompi una sessione di widget nativo completo e opzionalmente persisti lo stato finale.
`getWidgetSession`	Leggi una sessione di widget nativo completo.
`listWidgetSessions`	Elenco tutte le sessioni di widget nativo completo.
`sendWidgetMessage`	Incolli 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

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

CapgoTemplateWidgetBridge risolve una superficie di template SVG in svg, frameId, hotspotsEcco le informazioni e i metadati.
CapgoTemplateActionIntent Collega i pulsanti widget iOS interattivi alle azioni del modello.
CapgoNativeWidgetBridge Carica le sessioni e i messaggi full-native dal widget nativo code.
Gli aiuti del modello 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.

Se stai utilizzando @capgo/capacitor-widget-kit per pianificare l'automazione CI/CD, connettilo con Usando @capgo/capacitor-kit di widget per la capacità nativa in Usando @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 per il flusso di lavoro del prodotto in Capgo Integrazioni, e Integrazione CI/CD per la dettagliata implementazione in Integrazione CI/CD.