@capgo/capacitor-widget-kit

Übersicht

@capgo/capacitor-widget-kit Gibt einem Capacitor-App zwei Möglichkeiten, Widgets und Live-Aktivitäten zu steuern:

• SVG-Vorlagenaktivitäten: Definieren Sie WidgetKit-Oberflächen als SVG, wechseln Sie benannte Frames von Tasten, 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 gerendert werden kann. Verwenden Sie voll-natürliche Sitzungen, wenn das Widget eine benutzerdefinierte native UI benötigt, aber noch Starten, Stoppen, Synchronisieren von Zuständen oder die App bitten muss, um asynche Arbeit abzuschließen.

Demonstration

Widget-Vorlagen-Fluss

Wählen Sie eine Modus

Modus	Best for	Haupt-APIs
SVG-Vorlagenaktivität	Live-Aktivitäten oder Widgetoberflächen, die von SVG-Ausgaben rendern	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 coexistieren. Zum Beispiel kann ein Workout-App eine SVG-Live-Aktivität für schnelle Frame/Zählersteuerung und eine voll-nativer Widget-Sitzung für eine Home-Screen-Widget mit einem reicheren nativen Layout verwenden.

SVG-Vorlageneigenschaften

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

• frames Haltbare benannte SVG-Varianten wie summary, timer, oder details.
• frameMutations Schalt, umschalten oder durch die Frames nach einer Hotspot-Aktion gehen.
• timerMutations Starten, pausieren, wieder aufnehmen, umschalten, zurücksetzen, stoppen oder die Timerdauer ändern.
• patches Aktualisieren Sie den JSON-Zustand mit Literalwerten, Mustern, Zeitstempeln, Inkrementen, Umschaltungen oder Löschoperationen.
• hotspots Tippen Sie auf Bereiche, um Aktionen zu identifizieren.
• listTemplateEvents Lassen Sie das App-Widget-Programm die von dem Widget ausgelösten Aktionen später verarbeiten.

Die Ausführung löst Platzhalter wie __CAPGO_KEEP_0__ 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:

Erstellt gemeinsamen Zustand und Metadaten für das native Widget __CAPGO_KEEP_0__.

• startWidgetSession Erstellt gemeinsamen Zustand und Metadaten für das native Widget code.
• updateWidgetSession Mergt oder ersetzt den Zustand und markiert die Sitzung als aktiv wieder.
• stopWidgetSession Eine letzte Zustandsaufzeichnung und die Sitzung als beendet markiert.
• sendWidgetMessage App-zu-Widget- oder Widget-zu-App-Arbeit in der Warteschleife.
• acknowledgeWidgetMessages Nachrichten als empfangen markiert.
• completeWidgetMessage Ein Antwort- oder Fehler-Status für asynchrone Jobs speichert.

Nach der Beendigung sind Nachrichten idempotent: Eine Wiederholung 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 Vorlage-Bridge für Aktivitäten auf dem aktuellen Gerät ausgeführt werden kann.
startTemplateActivity	Eine SVG-Vorlage für Aktivitäten speichern und die native Live-Aktivitätsbrücke starten.
updateTemplateActivity	Ersetzen Sie die Aktivitätsdefinition, den Zustand oder öffnen Sie eine URL.
endTemplateActivity	Beenden Sie eine laufende Aktivität und optional persistieren Sie 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ändig-native Widget-Sitzung, die durch gemeinsam genutzten JSON-Zustand unterstützt wird.
updateWidgetSession	Mischen oder ersetzen Sie den Zustand einer vollständig-native Widget-Sitzung.
stopWidgetSession	Beenden Sie eine vollständig-native Widget-Sitzung und optional persistieren Sie den finalen Zustand.
getWidgetSession	Lesen Sie eine vollständig-native Widget-Sitzung.
listWidgetSessions	Listen Sie alle vollständig-native Widget-Sitzungen.
sendWidgetMessage	Warteschleife eine Nachricht zwischen der App und dem nativen Widget code.
listWidgetMessages	Liste der in der Warteschleife befindlichen Brückennachrichten.
acknowledgeWidgetMessages	Markiere Brückennachrichten als bestätigt.
completeWidgetMessage	Erledigen oder fehlschlagen Sie einen asynchronen Brückennachrichten.
getPluginVersion	Rufen Sie die Versionsnummer der Plattformimplementierung ab.

Native Teile

Das Plugin liefert auch native Hilfsmittel für Zielwidgete:

• CapgoTemplateWidgetBridge löst eine SVG-Vorlageoberfläche in svg, frameId, hotspotsund Metadaten auf.
• CapgoTemplateActionIntent verbindet interaktive iOS-Widget-Buttons mit Vorlagenvorgängen.
• CapgoNativeWidgetBridge lädt vollständige native Sitzungen und Nachrichten aus dem nativen Widget code.
• Android-Hilfsfunktionen liefern passende Aktionsempfänger- und Widget-Brückenverhalten.

Quelle der Wahrheit

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

Bleiben Sie bei @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 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