@capgo/capacitor-widget-kit

Übersicht

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

• SVG-Vorlagen-Aktivitäten: Definieren Sie WidgetKit-Oberflächen als SVG, wechseln Sie benannte Frames von Tasten, starten Sie Timer, ändern Sie JSON-Zustand und sammeln Sie Ereignisse in der App.
• Voll-nativer Widget-Sitzungen: Halten Sie die Widget-UI vollständig in Swift/Kotlin/Java, während Capacitor gemeinsamen JSON-Zustand und App-zu-Widget- oder Widget-zu-App-Nachrichten besitzt.

Verwenden Sie SVG-Vorlagen, wenn Ihr Widget aus aufgelösten SVG-Strings gerendert werden kann. Verwenden Sie voll-nativen Sitzungen, wenn das Widget eine benutzerdefinierte native UI benötigt, aber trotzdem starten, stoppen, den Zustand synchronisieren oder die App auffordern muss, asynche Arbeit abzuschließen.

Wählen Sie eine Modus

Modus	Am besten geeignet für	Haupt-APIs
SVG-Vorlagenaktivität	Lebendige Aktivitäten oder Widgetoberflächen, die von SVG-Ausgaben rendern	startTemplateActivity, performTemplateAction, listTemplateEvents
Voll-nativer Widget-Sitzung	Widgets, die nativ gerendert werden und gemeinsamen Zustand und asynchrone Aufgaben benötigen	startWidgetSession, updateWidgetSession, sendWidgetMessage

Beide Modi können in derselben App coexistieren. Zum Beispiel kann ein Workout-App einen SVG-Lebendigen Aktivitäten für schnelle Frame/Zählersteuerungen und eine voll-nativen Widget-Sitzung für eine Home-Screen-Widget mit einem reicheren nativen Layout verwenden.

SVG-Vorlagenfunktionen

SVG-Vorlagen enthalten die erforderlichen Teile für interaktive Widgetoberflächen:

• frames halten benannte SVG-Varianten wie summary, timer, oder details.
• frameMutations wechseln, schalten, oder durchlaufen Sie Frames nach einer Hotspotaktion.
• timerMutations starten, pausieren, fortsetzen, schalten, zurücksetzen, stoppen, oder ändern Sie die Timerdauer.
• patches aktualisieren Sie JSON-Zustände mit Literalwerten, Vorlagen, Zeitstempeln, Inkrementen, Schaltern oder Löschoperationen.
• hotspots mappen Sie Berührungsbereiche auf Aktionen identifizieren.
• listTemplateEvents erlaubt dem App-Prozess, Aktionen, die von Widgets stammen, später zu verarbeiten.

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

Voll-Native Bridge-Fähigkeiten

Voll-native-Sitzungen sind für Widgets vorgesehen, die ihre eigene UI natively rendern:

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

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

Öffentliche API

Methode	Beschreibung
areActivitiesSupported	Überprüfen Sie, ob die native Template-Aktivitätsbrücke auf dem aktuellen Gerät ausgeführt werden kann.
startTemplateActivity	Speichern Sie ein SVG-Template-Aktivität 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 einen letzten Zustands-Snapshot.
performTemplateAction	Ausführen Sie deklarative Patches, Frame-Mutationen, Timer-Mutationen und Ereignis-Protokollierungen.
getTemplateActivity	Lesen Sie eine gespeicherte Template-Aktivität.
listTemplateActivities	Listen Sie alle gespeicherten Template-Aktivitäten.
listTemplateEvents	Lesen Sie Ereignisse, die von Template-Aktionen emittiert wurden.
acknowledgeTemplateEvents	Markieren Sie Template-Ereignisse als bearbeitet.
startWidgetSession	Starten Sie eine vollständige native Widget-Sitzung, die durch gemeinsam verwendete JSON-Zustände unterstützt wird.
updateWidgetSession	Mischen oder ersetzen Sie den Zustand einer vollständigen native Widget-Sitzung.
stopWidgetSession	Beenden Sie eine vollständige nativ-Widget-Sitzung und speichern Sie optional den finalen Zustand.
getWidgetSession	Einen vollständigen nativ-Widget-Sitzung lesen.
listWidgetSessions	Alle vollständigen nativ-Widget-Sitzungen auflisten.
sendWidgetMessage	Eine Nachricht zwischen der App und dem nativen Widget code in der Warteschlange legen.
listWidgetMessages	Die in der Warteschlange stehenden Bridge-Nachrichten auflisten.
acknowledgeWidgetMessages	Bridge-Nachrichten als bestätigt markieren.
completeWidgetMessage	Ein asynchroner Bridge-Nachricht abschließen oder fehlschlagen.
getPluginVersion	Die Versionsmarke der Plattformimplementierung zurückgeben.

Native Pieces

Das Plugin liefert auch native Hilfsfunktionen für Widget-Ziele:

• CapgoTemplateWidgetBridge eine SVG-Vorlageoberfläche auflöst svg, frameId, hotspots, und Metadaten.
• CapgoTemplateActionIntent Verbindet interaktive iOS-Widget-Buttons mit Vorlagenaktionen.
• CapgoNativeWidgetBridge Lädt vollständige native Sitzungen und Nachrichten von dem native Widget code.
• Android-Vorlagenhelfer bieten übereinstimmende Aktionsempfänger- und Widget-Brückenverhalten.

Quelle der Wahrheit

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