@capgo/capacitor-widget-kit

Übersicht

@capgo/capacitor-widget-kit gibt einem 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 Pause-/Wiedergabe-Timer, ändern Sie JSON-Zustand und sammeln Sie Ereignisse in der App.
• Vollnativer 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 renderbar ist. Verwenden Sie voll-native Sitzungen, wenn das Widget eine benutzerdefinierte native Benutzeroberfläche benötigt, aber immer noch starten, stoppen, den Zustand synchronisieren oder die Anwendung um asynche Arbeit bitten muss.

Wählen Sie eine Modus

Am besten für	Haupt-APIs	SVG-Vorlagenaktivität
Live-Aktivitäten oder Widgetoberflächen, die aus SVG-Ausgaben renderen	Voll-native Widget-Sitzung	startTemplateActivity, performTemplateAction, listTemplateEvents
Widgets, die native renderen und gemeinsamen Zustand und asynche Aufgaben benötigen	Beide Modi können in derselben App coexistieren. Zum Beispiel kann ein Workout-App ein SVG-Live-Aktivität für schnelle Frame/Zählersteuerung und eine voll-native Widget-Sitzung für eine Home-Screen-Widget mit einer reicheren native Layout verwenden.	startWidgetSession, updateWidgetSession, sendWidgetMessage

SVG-Vorlagenfunktionen

Choose A Mode

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

• frames Haltbare SVG-Varianten wie summary, timer, oder details.
• frameMutations Schaltfläche, Schalter, oder durch Frames nach einem Hotspot-Aktion schalten.
• timerMutations Starten, pausieren, fortsetzen, schalten, zurücksetzen, stoppen oder die Timerdauer ändern.
• patches Aktualisieren Sie den JSON-Zustand mit Literalwerten, Mustern, Zeitstempeln, Inkrementen, Schaltern oder Unset-Operationen.
• hotspots Mappen Sie Berührungsbereiche auf Aktionenidentifikatoren.
• listTemplateEvents Lassen Sie das App-Verfahren die von Widgets ausgelösten Aktionen später ausführen.

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

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 rekordiert einen letzten Zustand und markiert die Sitzung als gestoppt.
• sendWidgetMessage wirkt App-zu-Widget- oder Widget-zu-App-Aufgaben ab.
• 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 zurück, anstatt es zu überschreiben.

Öffentliches 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 von deklarativen 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 werden.
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	Mergen oder ersetzen Sie einen vollständigen nativen Widget-Sitzungsstatus.
stopWidgetSession	Beenden Sie eine vollständige nativere Widget-Sitzung und speichern Sie optional den finalen Status.
getWidgetSession	Lesen Sie eine vollständige nativere Widget-Sitzung.
listWidgetSessions	Listen Sie alle vollständigen nativen Widget-Sitzungen.
sendWidgetMessage	Warten Sie auf eine Nachricht zwischen der App und dem nativen Widget code.
listWidgetMessages	Listen Sie die in der Warteschleife stehenden Bridge-Nachrichten.
acknowledgeWidgetMessages	Melden Sie Bridge-Nachrichten als bestätigt.
completeWidgetMessage	Erledigen Sie oder feiern Sie einen asynchronen Bridge-Nachrichten.
getPluginVersion	Rufen Sie die Versionsmarke der Plattformimplementierung ab.

Nativstücke

Das Plugin liefert auch native Hilfsfunktionen für Zielwidgete:

• CapgoTemplateWidgetBridge löst eine SVG-Vorlageoberfläche auf svg, frameId, hotspots, und Metadaten.
• CapgoTemplateActionIntent Verbindet interaktive iOS-Widget-Buttons mit Vorlagenvorgängen.
• CapgoNativeWidgetBridge Lädt vollständige native Sitzungen und Nachrichten von native Widgeten code.
• Android-Vorlagenhilfen bieten übereinstimmendes Aktionsempfänger- und Widgetbrücke-Verhalten.

Quelle der Wahrheit

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