@capgo/capacitor-kit-di-widget

WidgetKit e attività Live per le app Capacitor, con template SVG o sincronizzazione dello stato del widget nativo completo.

Avvia GitHub

Panoramica

@capgo/capacitor-widget-kit dà a un'app Capacitor due modi per gestire i widget e le attività in diretta.

Sessioni di widget nativo completo: mantiene l'interfaccia utente del widget completamente in Swift/Kotlin/Java mentre __CAPGO_KEEP_0__ possiede uno stato JSON condiviso e messaggi app-to-widget o widget-to-app.
Sessioni widget native complete: mantenere 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 template SVG quando il tuo 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.

Demo

Esempio animato di WidgetKit che mostra lo stato e i controlli del template widget guidati da Capacitor — Flusso del template del widget

Scegli un Modo

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

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

Capacità del modello SVG

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

frames varianti di SVG denominate con nome come summary, timero details.
frameMutations passare da una fase all'altra dopo un'azione su un hotspot.
timerMutations inizia, pausa, ripristina, alternare, resetta, fermati, o modifica la durata del timer.
patches aggiornare lo stato JSON utilizzando valori letterali, modelli, timestamp, incrementi, abilitazioni/disabilitazioni o operazioni di cancellazione.
hotspots mappare aree di tocco a identificatori di azione.
listTemplateEvents lets the app process widget-originated actions later.

La 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 i 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 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 segnala i messaggi come ricevuti.
completeWidgetMessage memorizza una risposta o un fallimento per i lavori asincroni.

Il messaggio è idempotente dopo la completamento: riprovare 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 sul dispositivo corrente.
`startTemplateActivity`	Persista un template di attività SVG e avvia il ponte di attività nativo Live.
`updateTemplateActivity`	Sostituisca la definizione, lo stato o l'URL aperto dell'attività.
`endTemplateActivity`	Termina un'attività in esecuzione e persista eventualmente uno stato di snapshot finale.
`performTemplateAction`	Esegui patch dichiarative, mutazioni di frame, mutazioni di timer e registrazione degli eventi.
`getTemplateActivity`	Legga un'attività di template memorizzata.
`listTemplateActivities`	Elencare tutte le attività dei template archiviati.
`listTemplateEvents`	Leggere gli eventi di azione emessi dalle azioni dei template.
`acknowledgeTemplateEvents`	Segnalare gli eventi dei template come elaborati.
`startWidgetSession`	Avviare una sessione di widget nativo completa supportata da uno stato JSON condiviso.
`updateWidgetSession`	Unire o sostituire uno stato di sessione di widget nativo completo.
`stopWidgetSession`	Sospendere una sessione di widget nativo e, facoltativamente, persistere lo stato finale.
`getWidgetSession`	Leggere una sessione di widget nativo completa.
`listWidgetSessions`	Elencare tutte le sessioni di widget nativo.
`sendWidgetMessage`	Incolonnare 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`	Restituisci il marchio di versione dell'implementazione della piattaforma.

Pezzi nativi

Il plugin fornisce anche aiuti nativi per i bersagli widget:

CapgoTemplateWidgetBridge risolve una superficie di modello SVG in svg, frameId, hotspotse metadati.
CapgoTemplateActionIntent connette pulsanti widget interattivi iOS a azioni di modello.
CapgoNativeWidgetBridge carica sessioni e messaggi full-native da widget code.
Aiuto dei template Android fornisce comportamento di ricezione di azione e ponte widget corrispondenti.

Fonte di verità

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

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