@capgo/capacitor-widget-kit
Übersicht
Abschnitt mit dem Titel „Ü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-Zustand 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 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 gerendert werden kann. Verwenden Sie voll-nativen Sitzungen, wenn das Widget eine benutzerdefinierte native UI benötigt, aber trotzdem starten, stoppen, den Zustand synchronisieren oder die App auffordern muss, asynche Arbeit abzuschließen.
Wählen Sie eine Modus
Abschnitt mit dem Titel „Wählen Sie eine Modus”| Modus | Am besten geeignet für | Haupt-APIs |
|---|---|---|
| SVG-Vorlagenaktivität | Lebendige 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 einen SVG-Lebendigen Aktivitäten für schnelle Frame/Zählersteuerungen und eine voll-nativen Widget-Sitzung für eine Home-Screen-Widget mit einem reicheren nativen Layout verwenden.
SVG-Vorlagenfunktionen
Abschnitt mit dem Titel „SVG-Vorlagenfunktionen”SVG-Vorlagen enthalten die erforderlichen Teile für interaktive Widgetoberflächen:
frameshalten benannte SVG-Varianten wiesummary,timer, oderdetails.frameMutationswechseln, schalten, oder durchlaufen Sie Frames nach einer Hotspotaktion.timerMutationsstarten, pausieren, fortsetzen, schalten, zurücksetzen, stoppen, oder ändern Sie die Timerdauer.patchesaktualisieren Sie JSON-Zustände mit Literalwerten, Vorlagen, Zeitstempeln, Inkrementen, Schaltern oder Löschoperationen.hotspotsmappen Sie Berührungsbereiche auf Aktionen identifizieren.listTemplateEventserlaubt dem App-Prozess, Aktionen, die von Widgets stammen, später zu verarbeiten.
Die Laufzeit löst Platzhalter wie {{state.title}}, {{timers.rest.remainingText}}, und {{meta.template.kind}} vor der nativen Brücke zurückgibt eine Oberfläche für das Rendering.
Voll-Native Bridge-Fähigkeiten
Abschnitt mit dem Titel “Voll-Native-Bridge-Funktionen”Voll-native-Sitzungen sind für Widgets vorgesehen, die ihre eigene UI natively rendern:
startWidgetSessionerstellt gemeinsame Zustände und Metadaten für das native Widget code.updateWidgetSessionvereint oder ersetzt Zustände und markiert die Sitzung als aktiv wieder.stopWidgetSessionfür einen letzten Zustand und markiert die Sitzung als gestoppt.sendWidgetMessagewirkt App-zu-Widget- oder Widget-zu-App-Aufgaben an.acknowledgeWidgetMessagesmarkiert Nachrichten als empfangen.completeWidgetMessagespeichert eine Antwort oder einen Fehler für asynche Aufgaben.
Nachrichten sind idempotent nach Abschluss: Eine Wiederholung einer abgeschlossenen oder fehlgeschlagenen Nachricht gibt das bestehende Ergebnis zurück, anstatt es zu überschreiben.
Öffentliche API
Abschnitt mit dem Titel “Öffentliche 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 Sie deklarative 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 wurden. |
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 | Mischen oder ersetzen Sie den Zustand einer vollständigen native Widget-Sitzung. |
stopWidgetSession | Beenden Sie eine vollständige nativ-Widget-Sitzung und speichern Sie optional den finalen Zustand. |
getWidgetSession | Einen vollständigen nativ-Widget-Sitzung lesen. |
listWidgetSessions | Alle vollständigen nativ-Widget-Sitzungen auflisten. |
sendWidgetMessage | Eine Nachricht zwischen der App und dem nativen Widget code in der Warteschlange legen. |
listWidgetMessages | Die in der Warteschlange stehenden Bridge-Nachrichten auflisten. |
acknowledgeWidgetMessages | Bridge-Nachrichten als bestätigt markieren. |
completeWidgetMessage | Ein asynchroner Bridge-Nachricht abschließen oder fehlschlagen. |
getPluginVersion | Die Versionsmarke der Plattformimplementierung zurückgeben. |
Native Pieces
Abschnitt mit dem Titel “Native Pieces”Das Plugin liefert auch native Hilfsfunktionen für Widget-Ziele:
CapgoTemplateWidgetBridgeeine SVG-Vorlageoberfläche auflöstsvg,frameId,hotspots, und Metadaten.CapgoTemplateActionIntentVerbindet interaktive iOS-Widget-Buttons mit Vorlagenaktionen.CapgoNativeWidgetBridgeLädt vollständige native Sitzungen und Nachrichten von dem native Widget code.- Android-Vorlagenhelfer bieten übereinstimmende Aktionsempfänger- und Widget-Brückenverhalten.
Quelle der Wahrheit
Abschnitt mit dem Titel „Quelle der Wahrheit“Die API-Referenz wird von src/definitions.ts im Plugin-Repository.