@capgo/capacitor-widget-kit

Panoramica

Crea interfacce WidgetKit e Live Activity da Capacitor con frame SVG, timer, hotspot di azione o sincronizzazione nativa dello stato del widget

Inizia con areActivitiesSupported() e gli altri metodi principali elencati qui sotto.

Supporto piattaforme

Piattaforma	Supporto	Note
iOS	Sì	Nativo
Android	Sì	Nativo
Web	No	Proteggi con Capacitor.getPlatform()

Siri, Shortcuts e App Intents

Widget Kit è hai un bridge per Siri o Shortcuts. Supporta WidgetKit, i template Live Activities di ActivityKit e i controlli interattivi iOS tramite tipi LiveActivityIntent in bundle (CapgoTemplateActionIntent, CompleteSetIntent) che aggiornano lo stato del template memorizzato e aggiungono al log degli eventi (listTemplateEvents / acknowledgeTemplateEvents).

Supporta hai registrare frasi di scelta rapida personalizzate, AppShortcutsProvider, cataloghi di entità JavaScript, elementi Spotlight o schemi delle app Apple. Usa @capgo/capacitor-app-intents per questi. Per un confronto completo con strumenti come expo-app-intents, vedi Siri, Shortcuts e widget.

Demo

Flusso del template Widget

Scegli una modalità

Modalità	Ideale per	API principali
Attività tramite template SVG	Live Activities o superfici widget renderizzate da output SVG	startTemplateActivity, performTemplateAction, listTemplateEvents
Sessione widget full-native	Widget renderizzati nativamente che richiedono stato condiviso e job asincroni	startWidgetSession, updateWidgetSession, sendWidgetMessage

Entrambe le modalità possono coesistere nella stessa app. Ad esempio, un'app di fitness può usare una Live Activity SVG per controlli rapidi di timer/frame e una sessione widget full-native per un widget in home screen con un layout nativo più ricco.

Capacità dei template SVG

I template SVG includono gli elementi necessari per superfici widget interattive:

• frames contengono varianti SVG nominate come summary, timer, o details.
• frameMutations switch, toggle o il passaggio tra i frame dopo un'azione hotspot.
• timerMutations avviare, mettere in pausa, riprendere, attivare, resettare, fermare o cambiare la durata del timer.
• patches aggiornare lo stato JSON tramite valori letterali, template, timestamp, incrementi, toggle o operazioni di unset.
• hotspots mappa le aree di tap agli identificatori delle azioni.
• listTemplateEvents permette all'app di elaborare in seguito le azioni provenienti dal widget.

Il runtime risolve i placeholder come {{state.title}}, {{timers.rest.remainingText}}, e {{meta.template.kind}} prima che il bridge nativo restituisca una superficie per il rendering.

Capacità del bridge full-native

Le sessioni full-native sono per i widget che renderizzano la propria UI nativamente:

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

I messaggi sono idempotenti dopo il completamento: riprovare un messaggio completato o fallito restituisce il risultato esistente invece di sovrascriverlo.

Pubblico API

Metodo	Descrizione
areActivitiesSupported	Verifica se il bridge dell'attività template nativa può essere eseguito sul dispositivo corrente.
startTemplateActivity	Persisti un'attività di template SVG e avvia il bridge nativo di Live Activity.
updateTemplateActivity	Sostituisci la definizione dell'attività, lo stato o l'URL di apertura.
endTemplateActivity	Termina un'attività in esecuzione e, opzionalmente, salva un ultimo snapshot dello stato.
performTemplateAction	Esegui patch dichiarative, mutazioni di frame e timer, e il logging degli eventi.
getTemplateActivity	Leggi un'attività di template salvata.
listTemplateActivities	Elenca tutte le attività di template salvate.
listTemplateEvents	Leggi gli eventi di azione emessi dalle azioni del template.
acknowledgeTemplateEvents	Segna gli eventi del template come elaborati.
startWidgetSession	Avvia una sessione widget full-native basata su uno stato JSON condiviso.
updateWidgetSession	Unisci o sostituisci lo stato di una sessione widget full-native.
stopWidgetSession	Ferma una sessione widget full-native e, opzionalmente, salva lo stato finale.
getWidgetSession	Leggi una sessione widget full-native.
listWidgetSessions	Elenca tutte le sessioni widget full-native.
sendWidgetMessage	Metti in coda un messaggio tra l'app e il widget nativo code.
listWidgetMessages	Elenca i messaggi del bridge in coda.
acknowledgeWidgetMessages	Segna i messaggi del bridge come confermati.
completeWidgetMessage	Completa o fai fallire un messaggio del bridge async.
getPluginVersion	Return the platform implementation version marker.

Componenti nativi

Il plugin include anche helper nativi per i target dei widget:

• CapgoTemplateWidgetBridge risolve una superficie template SVG in svg, frameId, hotspots, e metadati.
• CapgoTemplateActionIntent collega i pulsanti interattivi dei widget iOS alle azioni del template.
• CapgoNativeWidgetBridge carica sessioni e messaggi full-native dal widget code nativo.
• Gli helper del template Android forniscono un comportamento coerente per l'action receiver e il widget bridge.

Fonte di verità

Il riferimento API viene sincronizzato da src/definitions.ts nel repository del plugin.

Continua da @capgo/capacitor-widget-kit

Se stai usando @capgo/capacitor-widget-kit per pianificare l'automazione CI/CD e connetterla a Utilizzo di @capgo/capacitor-widget-kit per la funzionalità nativa in Utilizzo di @capgo/capacitor-widget-kit, CI/CD con Capgo per il workflow del prodotto in Capgo CI/CD, Capgo Native Build per il workflow di prodotto in Capgo Native Builds, Integrazioni Capgo per il workflow di prodotto in Integrazioni Capgo, e Integrazione CI/CD per i dettagli di implementazione in Integrazione CI/CD.