@capgo/capacitor-WidgetKit

Übersicht

@capgo/capacitor-widget-kit erläutert, wie eine Capacitor-App zwei Möglichkeiten zur Steuerung von Widgets und Live-Aktivitäten bietet:

• SVG-Vorlagen für Aktivitäten: Definieren Sie WidgetKit-Oberflächen als SVG, wechseln Sie benannte Frames von Tasten, starten Sie Timer, pausieren Sie sie oder ändern Sie JSON-Zustände und sammeln Sie Ereignisse aus der App.
• Voll-nativer Widget-Sitzungen: Halten Sie die Widget-UI vollständig in Swift/Kotlin/Java, während Capacitor gemeinsame JSON-Zustände und Nachrichten zwischen der App und dem Widget oder vom Widget zur App besitzt.

Verwenden Sie SVG-Vorlagen, wenn Ihr Widget aus SVG-Strings erzeugt werden kann. Verwenden Sie voll-nativen Sitzungen, wenn das Widget eine benutzerdefinierte native UI benötigt, aber immer noch starten, stoppen, synchronisieren oder die App auffordern muss, asynchrone Arbeit abzuschließen.

Demo

Widget-Template-Fluss

Wählen Sie einen Modus

Modus	Am besten geeignet für	Haupt-APIs
SVG-Template-Aktivität	Lebendige Aktivitäten oder Widget-Oberflächen, die von SVG-Ausgaben renderen	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 leben. Zum Beispiel kann ein Workout-App ein SVG-Lebendes Ereignis für schnelle Frame/Zählersteuerungen und eine vollständige native Widget-Sitzung für einen Homescreen-Widget mit einem reicheren nativen Layout verwenden.

SVG-Vorlagenfunktionen

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

• frames halten benannte SVG-Varianten wie summary, timer, oder details.
• frameMutations wechseln, umschalten, oder durch Frame nach einem Hotspot-Aktion zu schalten.
• timerMutations starten, pausieren, fortsetzen, umschalten, zurücksetzen, stoppen oder die Timerdauer ändern.
• patches aktualisieren Sie den JSON-Zustand mit Literalwerten, Vorlagen, Zeitstempeln, Inkrementen, Schaltern oder Unset-Befehlen.
• hotspots mappen Sie Berührungsbereiche auf Aktionenidentifikatoren.
• listTemplateEvents erlaubt dem App-Prozess, Widget-geleitete Aktionen später zu verarbeiten.

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

Voll-Native-Bridge-Funktionen

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 rekordiert einen finalen Zustand und markiert die Sitzung als gestoppt.
• sendWidgetMessage Warteschlangen für app-zu-Widget- oder Widget-zu-App-Aufgaben.
• acknowledgeWidgetMessages markiert Nachrichten als empfangen.
• completeWidgetMessage speichert eine Antwort oder einen Fehler für asynchrone Aufgaben.

Nachrichten sind idempotent nach Abschluss: Eine erneute Ausführung einer abgeschlossenen oder fehlgeschlagenen Nachricht gibt den bestehenden Ergebnis anstatt es zu überschreiben.

Öffentlich 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 ein letztes Zustands-Snapshot.
performTemplateAction	Ausführen Sie deklarative Patches, Frame-Mutationen, Timer-Mutationen und Ereignis-Protokollierung.
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 werden.
acknowledgeTemplateEvents	Markiere Vorlagenereignisse als bearbeitet.
startWidgetSession	Starte eine vollständige nativ-basierte Widget-Sitzung, die durch gemeinsame JSON-Zustandsdaten unterstützt wird.
updateWidgetSession	Mische oder ersetze den Zustand einer vollständigen nativ-basierten Widget-Sitzung.
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	Liste alle vollständigen nativ-basierten Widget-Sitzungen.
sendWidgetMessage	Stelle eine Nachricht zwischen der App und dem nativen Widget code an.
listWidgetMessages	Liste die in der Warteschlange befindlichen Bridge-Nachrichten.
acknowledgeWidgetMessages	Markiere Bridge-Nachrichten als bestätigt.
completeWidgetMessage	Erledige oder fehle einen asynchronen Bridge-Nachricht.
getPluginVersion	Gib die Versionsmarke der Plattformimplementierung zurück.

Nativteile

Der Plugin sendet auch native Hilfsmittel für Zielwidget:

• CapgoTemplateWidgetBridge löst ein SVG-Vorlagenoberfläche in svg, frameId, hotspots, und Metadaten.
• CapgoTemplateActionIntent verbindet interaktive iOS-Widget-Tasten mit Vorlagenaktionen.
• CapgoNativeWidgetBridge lädt vollständige native Sitzungen und Nachrichten von native Widget code.
• Android-Vorlagenhilfen bieten entsprechende Aktionsempfänger- und Widget-Brückenverhalten.

Quelle der Wahrheit

Der API-Bezug wird von src/definitions.ts in dem Plugin-Repository synchronisiert.

Fahren Sie mit @capgo/capacitor-widget-kit fort.

Wenn Sie @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kit verwenden @capgo/capacitor-widget-kit verwenden Um @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kit mit @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kit zu verbinden @capgo/capacitor-widget-kit verwenden for the native capability in Using @capgo/capacitor-widget-kit, Capgo CI/CD für das Produktworkflow Capgo Native Builds Capgo Native Builds für das Produktworkflow Capgo Integrations Capgo Integrations für das Produktworkflow Capgo Integrations und CI/CD-Integration für die Implementierungsdetails in CI/CD-Integration.