@capgo/capacitor-WidgetKit

Übersicht

@capgo/capacitor-widget-kit ermöglicht es einer 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 renderbar ist. Verwenden Sie voll-nativen Sitzungen, wenn das Widget eine benutzerdefinierte native UI benötigt, aber noch immer starten, stoppen, den Zustand synchronisieren oder die App auffordern muss, asynche Arbeit abzuschließen.

Demo

Widget-Vorlagen-Fluss

Wähle 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 Widgetsitz	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 ein SVG-Lebendiges Aktivitätsfenster für schnelle Frame-/Timersteuerung und einen voll-nativen Widgetsitz für ein Home-Screen-Widget mit einem reicheren nativen Layout verwenden.

SVG-Template-Fähigkeiten

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

• frames Halten Sie benannte SVG-Varianten wie summary, timer, oder details.
• frameMutations Schalten Sie nach einem Hotspot-Aktionsschalter durch, um durch Frames zu schalten.
• timerMutations Starten, pausieren, fortsetzen, umschalten, zurücksetzen, stoppen oder die Timerdauer ändern.
• patches Aktualisieren Sie die JSON-Zustandsdaten mit Literalwerten, Mustern, Zeitstempeln, Inkrementen, Umschaltungen oder Löschoperationen.
• hotspots Zuweisen Sie Berührungsbereiche zu Aktionen identifizieren.
• listTemplateEvents erlaubt dem App-Verarbeitungsprozess Widget-geleitete Aktionen später.

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

Voll-Native-Brücke-Funktionen

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 wieder als aktiv.
• stopWidgetSession rekordiert einen finalen Zustand und markiert die Sitzung als gestoppt.
• sendWidgetMessage wirkt App-zu-Widget- oder Widget-zu-App-Aufgaben an.
• 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.

Öffentliche 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 ein letztes Zustands-Snapshot.
performTemplateAction	Ausführen Sie deklarative Patches, Frame-Mutationen, Timer-Mutationen und Ereignis-Protokollierung.
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	Einen vollständigen Widget-Sitzung starten, der von gemeinsam genutztem JSON-Zustand unterstützt wird.
updateWidgetSession	Mischen oder einen vollständigen Widget-Sitzungszustand ersetzen.
stopWidgetSession	Eine vollständige Widget-Sitzung beenden und optionalen den finalen Zustand speichern.
getWidgetSession	Eine vollständige Widget-Sitzung lesen.
listWidgetSessions	Alle vollständigen Widget-Sitzungen auflisten.
sendWidgetMessage	Queue a message between the app and native widget code.
listWidgetMessages	Die in der Warteschlange stehenden Bridge-Nachrichten auflisten.
acknowledgeWidgetMessages	Die Bridge-Nachrichten als bestätigt markieren.
completeWidgetMessage	Ein asynchroner Bridge-Nachrichten abschließen oder fehlschlagen.
getPluginVersion	Die Versionsmarke der Plattformimplementierung zurückgeben.

Nativteile

Das Plugin liefert auch native Hilfsfunktionen für Zielwidgete:

• CapgoTemplateWidgetBridge löst eine 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 Widgeten code.
• Android-Vorlagenhilfen bieten entsprechende Empfangs- und Brückenelemente für Widgets.

Quelle der Wahrheit

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

Weitermachen von @capgo/capacitor-widget-kit

If Sie __CAPGO_KEEP_0__ 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 for the product workflow in Capgo Integrations, and für den Produktworkflow in __CAPGO_KEEP_0__ Integrations, und das CI/CD-Integration {"targetLanguage":"German","pagePath":"/de/docs/plugins/widget-kit/","protectedTokens":["Cloudflare","Capacitor","GitHub","Capgo","code","API","SDK","CLI","npm","bun"],"items":[{"text":"Für die Implementierungsdetails in der CI/CD-Integration."},{"text":"Seite bearbeiten"}]}