@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 Taps, starten Sie Pause-/Wiedergabe-Timer, ändern Sie JSON-Zustände 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 gemeinsame JSON-Zustände und App-zu-Widget- oder Widget-zu-App-Nachrichten besitzt.

Verwenden Sie SVG-Vorlagen, wenn Ihr Widget aus aufgelösten SVG-Strings renderbar ist. Verwenden Sie voll-nativen Sitzungen, wenn das Widget eine benutzerdefinierte native UI benötigt, aber noch Starten, Stoppen, Synchronisieren von Zuständen oder die App bitten muss, asynche Arbeit abzuschließen.

Demo

Widget-Template-Fluss

Wählen Sie eine Modus

Modus	Am besten geeignet für	Haupt-APIs
SVG-Template-Aktivität	Live-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 Live Activity für schnelle Frame-/Timer-Steuerungen und eine vollständige native Widget-Sitzung für einen Home-Screen-Widget mit einem reicheren nativen Layout verwenden.

SVG-Vorlagenfunktionen

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

• frames Halten Sie benannte SVG-Varianten wie summary, timer, oder details.
• frameMutations Schalten, um, oder durch Schritte nach einem Hotspot-Aktion zu gehen.
• timerMutations Starten, pausieren, fortsetzen, umschalten, zurücksetzen, stoppen oder die Timerdauer ändern.
• patches Aktualisieren Sie die JSON-Zustandsdaten mit Literalwerten, Vorlagen, Zeitstempeln, Inkrementen, Schaltern oder Unset-Operationen.
• hotspots Zuordnen Sie Berührungsbereiche zu Aktionenidentifikatoren.
• listTemplateEvents erlaubt dem App-Verarbeitungsprozess, Widget-begonnene 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-Fähigkeiten

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

Nachrichten sind idempotent nach Abschluss: Wiederholen einer abgeschlossenen oder fehlgeschlagenen Nachricht gibt das bestehende 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 Warteschleife stehenden 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.

Nativstücke

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-Buttons mit Vorlagenaktionen.
• CapgoNativeWidgetBridge lädt vollständige native Sitzungen und Nachrichten von native Widget code.
• Android-Vorlagenhilfen liefern passende Aktionsempfänger- und Widget-Brückenverhalten.

Quelle der Wahrheit

Der API-Bezug wird von src/definitions.ts in der 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 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 Native Builds für den Produktworkflow in Capgo Native Builds Capgo Integrations für den Produktworkflow in Capgo Integrations und CI/CD-Integration für die Implementierungsdetails in CI/CD-Integration