@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-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 gerendert werden kann. Verwenden Sie voll-nativen Sitzungen, wenn das Widget eine benutzerdefinierte native UI benötigt, aber immer noch starten, stoppen, den Zustand synchronisieren oder die App auffordern muss, asynche Arbeit abzuschließen.

Demo

Widget-Vorlagen-Fluss

Wählen Sie eine Modus

Modus	Am besten geeignet für	Haupt-APIs
SVG-Vorlagenaktivität	Lebendige Aktivitäten oder Widgets, die von SVG-Ausgaben gerendert werden	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 eine SVG Live Activity 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

Haltbare SVG-Varianten wie

• frames , oder summary, timerSchalter, Taste, oder durch Hotspots ausgelöstes Frame-Wechseln. details.
• frameMutations Starten, Pausieren, Fortsetzen, Schalten, Zurücksetzen, Stoppen oder Timerdauer ändern.
• timerMutations Aktualisieren Sie den JSON-Zustand mit Literalwerten, Vorlagen, Zeitstempeln, Inkrementen, Schaltern oder Unset-Operationen.
• patches Mappen Sie Berührungsbereiche auf Aktionen zu.
• hotspots Lassen Sie das App-Verfahren die später von Widgets ausgelösten Aktionen verarbeiten.
• listTemplateEvents Die Laufzeit löst Platzhalter wie __CAPGO_KEEP_0__

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

Voll-Native-Brückenfunktionen

Voll-nativen Sitzungen werden für Widgets verwendet, 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 eine letzte Zustand aufzeichnet und die Sitzung als gestoppt markiert.
• sendWidgetMessage app-zu-Widget- oder Widget-zu-App-Aufgaben in einer Warteschlange platziert.
• acknowledgeWidgetMessages Nachrichten als empfangen markiert.
• completeWidgetMessage Antworten oder Fehler für asynchrone Jobs speichert.

Nachrichten sind idempotent nach Abschluss: 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 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-Protokollierung.
getTemplateActivity	Laden Sie eine gespeicherte Template-Aktivität.
listTemplateActivities	Liste aller gespeicherten Template-Aktivitäten.
listTemplateEvents	Laden Sie Ereignisse ab, die von Template-Aktionen emittiert wurden.
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 optionalen Endzustand.
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 alle in der Warteschlange befindlichen Brückenmeldungen.
acknowledgeWidgetMessages	Markiere Brückenmeldungen als bestätigt.
completeWidgetMessage	Erledige oder fehle einen asynchronen Brückenmessage.
getPluginVersion	Gib die Versionsmarke der Plattformimplementierung zurück.

Nativteile

Die Erweiterung liefert auch native Hilfsmittel für Zielwidgete:

• CapgoTemplateWidgetBridge eine SVG-Vorlageoberfläche in svg, frameId, hotspots, und Metadaten.
• CapgoTemplateActionIntent interaktive iOS-Widget-Buttons mit Vorlagenaufgaben verbindet.
• CapgoNativeWidgetBridge vollständige native Sitzungen und Nachrichten von native Widgeten code lädt.
• Android-Vorlagenhilfsmittel bieten entsprechendes Empfangsverhalten für Aktionen und Brückenverhalten für Widgets.

Quelle der Wahrheit

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

Fortsetzen von @capgo/capacitor-widget-kit

Wenn Sie @capgo/capacitor-widget-kit zur Planung der CI/CD-Automatisierung verwenden, 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 das Produktworkflow in Capgo CI/CD, Capgo Native Builds für das Produktworkflow in Capgo Native Builds, Capgo Integrations für das Produktworkflow in Capgo Integrations, und CI/CD-Integration für die Implementierungsdetails in der CI/CD-Integration.