@capgo/capacitor-WidgetKit

WidgetKit und Live-Aktivitäten für Capacitor-Apps, mit SVG-getriebenen Vorlagen oder vollständiger nativer Widget-Synchronisierung

Loslegen GitHub

Übersicht

@capgo/capacitor-widget-kit gibt einer Capacitor-App zwei Möglichkeiten, Widgets und Live-Aktivitäten zu steuern:

Vollnativer Widget-Sitzungen: Halten Sie die Widget-UI vollständig in Swift/Kotlin/Java, während __CAPGO_KEEP_0__ den gemeinsamen JSON-Zustand und die App-zu-Widget- oder Widget-zu-App-Nachrichten besitzt.
Vollständig-native Widget-Sitzungen: Halten Sie die Widget-UI vollständig in Swift/Kotlin/Java, während Capacitor gemeinsame JSON-Zustände und Anwendungs- oder Widget-zu-Anwendungs- oder Widget-zu-Anwendungs-Meldungen besitzt.

Use SVG templates when your widget can be rendered from resolved SVG strings. Use full-native sessions when the widget needs a custom native UI but still has to start, stop, sync state, or ask the app to complete async work.

Demo

Wählen Sie eine Modus

Modus	Am besten für	Haupt-APIs
SVG-Vorlagenaktivität	Live-Aktivitäten oder Widgetoberflächen, die aus SVG-Ausgaben gerendert werden	`startTemplateActivity`, `performTemplateAction`, `listTemplateEvents`
Voll-nativer Widget-Sitzung	Nativ-generierte Widgets, die gemeinsame Zustände und asynchrone Aufgaben benötigen	`startWidgetSession`, `updateWidgetSession`, `sendWidgetMessage`

Beide Modi können in derselben App coexistieren. Zum Beispiel kann ein Workout-App ein SVG-Live-Activity für schnelle Frame-/Timersteuerungen und eine voll-nativer Widget-Sitzung für eine Homescreen-Widget mit einem reicheren nativen Layout verwenden.

SVG-Vorlagenfunktionen

SVG-Vorlagen enthalten die notwendigen Teile für interaktive Widget-Oberflächen:

frames Halten Sie benannte SVG-Varianten wie summary, timer, oder details.
frameMutations Schalten, umschalten, umschalten oder durch Frames nach einem Hotspot-Aktion zu schalten.
timerMutations Starten, pausieren, fortsetzen, umschalten, zurücksetzen, stoppen oder die Timerdauer ändern.
patches Aktualisieren Sie JSON-Zustände mit Literalwerten, Vorlagen, Zeitstempeln, Inkrementen, Schaltern oder Unset-Operationen.
hotspots Zuordnen Sie Berührungsbereiche zu Aktionen.
listTemplateEvents lässt das App-Verhalten auf Widget-Initiierungen später zu.

Die Laufzeit löst Platzhalter wie {{state.title}}, {{timers.rest.remainingText}}, und {{meta.template.kind}} vor der Rückkehr des nativen Brückens eine Oberfläche für das Rendering.

Voll-Native-Brückenfunktionen

Voll-nativen Sitzungen dienen für Widgets, die ihre eigene UI natively rendern:

startWidgetSession erstellt gemeinsame Zustände und Metadaten für den nativen Widget code.
updateWidgetSession vereint oder ersetzt Zustände und markiert die Sitzung als aktiv wieder.
stopWidgetSession rekordiert einen letzten Zustand und markiert die Sitzung als gestoppt.
sendWidgetMessage wartet auf App-zu-Widget- oder Widget-zu-App-Aufgaben.
acknowledgeWidgetMessages markiert Nachrichten als empfangen.
completeWidgetMessage speichert eine Antwort oder einen Fehler für asynche Aufgaben.

Nach Abschluss sind Nachrichten idempotent: Wiederholen einer abgeschlossenen oder fehlgeschlagenen Nachricht gibt das bestehende Ergebnis zurück, anstatt es zu überschreiben.

Öffentlich API

Methode	Beschreibung
`areActivitiesSupported`	Überprüfen, ob die native Vorlage-Bridge für Aktivitäten auf dem aktuellen Gerät ausgeführt werden kann.
`startTemplateActivity`	Speichern Sie ein SVG-Vorlagenauftrag und starten Sie die native Live-Aktivitätsbrücke.
`updateTemplateActivity`	Ersetzen Sie die Aktivitätsdefinition, den Zustand oder die geöffnete URL.
`endTemplateActivity`	Beenden Sie eine laufende Aktivität und speichern Sie optional ein letztes Zustands-Snapshot.
`performTemplateAction`	Führen Sie deklarative Patches, Frame-Mutationen, Timer-Mutationen und Ereignis-Protokollierung aus.
`getTemplateActivity`	Laden Sie eine gespeicherte Vorlagenauftrag ab.
`listTemplateActivities`	Liste aller gespeicherter Template-Aktivitäten.
`listTemplateEvents`	Lese Aktionsevents, die von Template-Aktionen ausgelöst werden.
`acknowledgeTemplateEvents`	Markiere Template-Ereignisse als bearbeitet.
`startWidgetSession`	Einen vollständigen Widget-Sitzung starten, der von gemeinsamem JSON-Zustand unterstützt wird.
`updateWidgetSession`	Ein vollständiges Widget-Sitzungsstate kombinieren oder ersetzen.
`stopWidgetSession`	Beende eine vollständige nativ-basierte Widget-Sitzung und speichere optional den finalen Zustand.
`getWidgetSession`	Lese eine vollständige nativ-basierte Widget-Sitzung.
`listWidgetSessions`	Alle vollständigen Widget-Sitzungen auflisten.
`sendWidgetMessage`	Stelle eine Nachricht zwischen der App und dem nativen Widget code an.
`listWidgetMessages`	Liste alle in der Warteschlange befindlichen Bridge-Nachrichten.
`acknowledgeWidgetMessages`	Markiere Bridge-Nachrichten als bestätigt.
`completeWidgetMessage`	Erledige oder fehle einen asynchronen Bridge-Nachrichten.
`getPluginVersion`	Gibt die Versionsmarke der Plattformimplementierung zurück.

Native Teile

Die Plugin liefert auch native Hilfsmittel für Widget-Ziele:

CapgoTemplateWidgetBridge wirft eine SVG-Vorlageoberfläche in svg, frameId, hotspots, und Metadaten.
CapgoTemplateActionIntent verbindet interaktive iOS-Widget-Buttons mit Vorlagenaufgaben.
CapgoNativeWidgetBridge lädt vollständige native Sitzungen und Nachrichten von native Widgeten code.
Android-Vorlagenhilfen bieten entsprechende Empfangs- und Brücke-Verhalten für Widgets.

Quelle der Wahrheit

Die API-Referenz wird von src/definitions.ts in der Plugin-Repository.

Wenn Sie “@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kit” verwenden @capgo/capacitor-Widget-Kit um die CI/CD-Automatisierung zu planen, verbinden Sie es mit Mit @capgo/capacitor-widget-kit für die native Fähigkeit in Mit @capgo/capacitor-widget-kit Capgo CI/CD für den Produktworkflow in Capgo CI/CD Capgo nativee native Builds für den Produktworkflow in Capgo Native Builds Capgo Integrations zur Produktionsablauf in Capgo Integrations, und CI/CD-Integration zur Implementierungsdetail in CI/CD-Integration.