@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 superfici WidgetKit come SVG, passa da frame nominati con i tocchi, esegui timer di pausa/riavvio, muta 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 ha bisogno di un'interfaccia utente nativa personalizzata ma deve ancora avviarsi, fermarsi, sincronizzare lo stato o chiedere all'app di completare il lavoro asincrono.

Demo

Ciclo del modello del widget

Scegli un Modalità

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

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

Capacità del modello SVG

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

• frames nome varianti SVG denominate come summary, timer, o details.
• frameMutations passare da un frame all'altro 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/disabilitazioni o operazioni di cancellazione.
• hotspots mappare aree di tocco a identificatori di azione.
• listTemplateEvents consente all'app 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 segnala la sessione attiva di nuovo.
• 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.

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

Publico API

Metodo	Descrizione
areActivitiesSupported	Verifica se il ponte di attività di template nativo può essere eseguito sul dispositivo corrente.
startTemplateActivity	Persisti un template di attività SVG e avvia il ponte di attività nativo Live.
updateTemplateActivity	Sostituisci la definizione, lo stato o l'URL aperto dell'attività.
endTemplateActivity	Termina un'attività in esecuzione e persisti eventualmente uno stato di snapshot finale.
performTemplateAction	Esegui patch dichiarative, mutazioni di frame, mutazioni di timer e registrazione degli eventi.
getTemplateActivity	Lega un template di attività archiviato.
listTemplateActivities	Elenco tutte le attività di template archiviate.
listTemplateEvents	Lega gli eventi di azione emessi dalle azioni di template.
acknowledgeTemplateEvents	Segnala eventi di template come elaborati.
startWidgetSession	Inizia una sessione di widget nativo a piena capacità supportata da uno stato JSON condiviso.
updateWidgetSession	Fusione 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 messaggi di ponte come riconosciuti.
completeWidgetMessage	Completa o falli 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 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.
• 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 in repository del plugin.

Continua da @capgo/capacitor-widget-kit

Se sei in uso a @capgo/capacitor-kit di widget per pianificare l'automazione CI/CD, connettilo con Utilizza @capgo/capacitor-kit di widget per la capacità nativa in Utilizza @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 for the product workflow in Capgo Integrations, and Integrazione CI/CD per i dettagli di implementazione nell'integrazione CI/CD