@capgo/capacitor-Widget-Kit

Übersicht

@capgo/capacitor-widget-kit gives a Capacitor app two ways to drive widgets and Live Activities:

• SVG-Vorlagenaktivitäten: Definieren Sie WidgetKit-Oberflächen als SVG, wechseln Sie benannte Frames von Taps, starten Sie Pause/Bildlauf-Timer, ändern Sie JSON-Zustände und sammeln Sie Ereignisse der Aktion 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-natürliche Sitzungen, wenn das Widget eine benutzerdefinierte native UI benötigt, aber trotzdem starten, stoppen, synchronisieren oder die App bitten muss, asynche Arbeit abzuschließen.

Demo

Widget-Vorlagenfluss

Wählen Sie eine Modus

Modus	Best für	Haupt-APIs
__CAPGO_KEEP_0__	Lebendige Aktivitäten oder Widgetoberflächen, die von SVG-Ausgaben rendern	startTemplateActivity, performTemplateAction, listTemplateEvents
Voll-nativer Widget-Sitzung	Nativ-generierte Widgets, die gemeinsame Zustände und asynchrone Aufgaben benötigen	startWidgetSession, updateWidgetSession, sendWidgetMessage

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

SVG-Vorlagenfähigkeiten

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

• frames Haltbare SVG-Varianten wie summary, timeroder details.
• frameMutations Schalter, Taste oder durch Hotspots nach Frames schalten, nachdem eine Hotspot-Aktion ausgelöst wurde.
• timerMutations Starten, Pausieren, Fortsetzen, Schalten, Zurücksetzen, Stoppen oder Timerdauer ändern.
• patches aktualisiert den JSON-Zustand mithilfe von Literalwerten, Mustern, Zeitstempeln, Inkrementen, Schaltflächen oder Löschoperationen.
• hotspots Kartiert Tastenbereiche auf Aktionen zu.
• listTemplateEvents erlaubt dem App-Prozess, Aktionen, die von Widgets ausgelöst wurden, später zu verarbeiten.

Die Ausführung löst Platzhalter wie __CAPGO_KEEP_0__ und __CAPGO_KEEP_1__ auf, bevor die native Brücke eine Oberfläche für das Rendering zurückgibt. {{state.title}}, {{timers.rest.remainingText}}Voll-Native-Brückenfunktionen {{meta.template.kind}} Abschnitt mit dem Titel „Voll-Native-Brückenfunktionen“

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

vereint oder ersetzt Zustand und markiert die Sitzung als aktiv wieder.

• startWidgetSession creates shared state and metadata for native widget code.
• updateWidgetSession erstellt gemeinsamen Zustand und Metadaten für native Widgets __CAPGO_KEEP_0__.
• stopWidgetSession vereint oder ersetzt Zustand und markiert die Sitzung als aktiv wieder.
• sendWidgetMessage Warteschlangen-app-zu-Widget oder Widget-zu-App-Arbeit.
• acknowledgeWidgetMessages Markiert Nachrichten als empfangen.
• completeWidgetMessage Speichert eine Antwort oder einen Fehler für asynchrone Aufträge.

Nachrichten sind idempotent nach Abschluss: Wiederholen eines abgeschlossenen oder fehlgeschlagenen Nachrichten gibt das bestehende Ergebnis zurück, anstatt es zu überschreiben.

Öffentlich API

Methode	Beschreibung
areActivitiesSupported	Überprüfen, ob die native Vorlage-Bridge für Aktivitäten auf dem aktuellen Gerät ausgeführt werden kann.
startTemplateActivity	Eine SVG-Vorlage für Aktivitäten persistieren und die native Live Activity-Bridge starten.
updateTemplateActivity	Ersetzen Sie die Aktivitätsdefinition, den Zustand oder die geöffnete URL.
endTemplateActivity	Eine laufende Aktivität beenden und optional eine letzte Zustands-Snapshot persistieren.
performTemplateAction	Deklarative Patches ausführen, Frame-Mutationen, Timer-Mutationen und Ereignisprotokollierung.
getTemplateActivity	Eine gespeicherte Template-Aktivität lesen.
listTemplateActivities	Alle gespeicherten Template-Aktivitäten auflisten.
listTemplateEvents	Aktionsevents, die von Template-Aktionen emittiert werden, lesen.
acknowledgeTemplateEvents	Template-Ereignisse als bearbeitet markieren.
startWidgetSession	Ein vollständig-native Widget-Sitzung starten, die durch gemeinsam genutztes JSON-Zustand unterstützt wird.
updateWidgetSession	Einen vollständig-native Widget-Sitzungszustand kombinieren oder ersetzen.
stopWidgetSession	Eine vollständig-native Widget-Sitzung beenden und optional den finalen Zustand persistieren.
getWidgetSession	Eine vollständig-native Widget-Sitzung lesen.
listWidgetSessions	Alle vollständig-native Widget-Sitzungen auflisten.
sendWidgetMessage	Ein Nachricht zwischen der App und dem native Widget code in der Warteschlange legen.
listWidgetMessages	Alle in der Warteschlange befindlichen Bridge-Nachrichten auflisten.
acknowledgeWidgetMessages	Marktbrückenmeldungen als bestätigt kennzeichnen.
completeWidgetMessage	Einen asynchronen Brückenmessage vollständig oder fehlschlagen.
getPluginVersion	Die Plattformimplementierungsversionssymbol markieren.

Native Teile

Das Plugin liefert auch native Hilfsmittel für Zielwidgete:

• CapgoTemplateWidgetBridge eine SVG-Vorlageoberfläche in svg, frameId, hotspots, und Metadaten auflöst.
• CapgoTemplateActionIntent interaktive iOS-Widget-Buttons mit Vorlagenaufgaben verbindet.
• CapgoNativeWidgetBridge Voll-native Sitzungen und Nachrichten von native Widgeten code lädt.
• Android-Vorlagenhilfsmittel bieten passende Empfänger- und Brückenverhalten für Widgets.

Quelle der Wahrheit

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

Fortsetzen Sie von @capgo/capacitor-Widget-Kit

Wenn Sie @capgo/capacitor-Widget-Kit zum Planen der CI/CD-Automatisierung verwenden, verbinden Sie es mit Mit @capgo/capacitor-Widget-Kit zur nativen Fähigkeit in Mit @capgo/capacitor-Widget-Kit, Capgo CI/CD zur 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 CI/CD-Integration.