Zum Inhalt springen

@capgo/capacitor-widget-kit

Erstelle WidgetKit- und Live-Activity-Oberflächen aus Capacitor – mit SVG-Frames, Timern, Action-Hotspots oder vollständig nativer Synchronisierung des Widget-States

Erstelle WidgetKit- und Live-Activity-Oberflächen aus Capacitor – mit SVG-Frames, Timern, Action-Hotspots oder vollständig nativer Synchronisierung des Widget-States

Starte mit areActivitiesSupported() und den anderen unten aufgeführten Core-Methoden.

PlattformSupportNotizen
iOSJaNativ
AndroidJaNativ
WebNeinAbsichern mit Capacitor.getPlatform()

Widget Kit ist es nicht eine Siri- oder Shortcuts-Bridge. Es unterstützt WidgetKit, ActivityKit-Templates für Live Activities sowie interaktive iOS-Controls über gebündelte LiveActivityIntent Typen (CapgoTemplateActionIntent, CompleteSetIntent), die den gespeicherten Template-State aktualisieren und den Template- Event-Log (listTemplateEvents / acknowledgeTemplateEvents).

Es unterstützt es nicht eigene Shortcut-Phrasen registrieren, AppShortcutsProvider, JavaScript-Entity-Kataloge, Spotlight-Einträge oder Apple-App-Schemas. Nutze @capgo/capacitor-app-intents dafür. Für einen vollständigen Vergleich mit Tools wie expo-app-intents, siehe Siri, Shortcuts und Widgets.

Animierte WidgetKit-Demo mit Template-Widget-Status und -Steuerelementen, gesteuert von Capacitor
Widget-Template-Flow
ModusIdeal fürHaupt-APIs
SVG-Template-ActivityLive Activities oder Widget-Oberflächen, die aus SVG-Output gerendert werdenstartTemplateActivity, performTemplateAction, listTemplateEvents
Full-Native-Widget-SessionNativ gerenderte Widgets, die Shared State und Async-Jobs brauchenstartWidgetSession, updateWidgetSession, sendWidgetMessage

Beide Modi können in derselben App verwendet werden. Eine Workout-App kann zum Beispiel eine SVG Live Activity für schnelle Frame-/Timer-Steuerungen und eine Full-Native-Widget-Session für ein Home-Screen-Widget mit einem umfangreicheren nativen Layout verwenden.

SVG-Templates enthalten die nötigen Bausteine für interaktive Widget-Oberflächen:

  • frames benannte SVG-Varianten halten wie summary, timer, oder details.
  • frameMutations Switch, Toggle oder das Durchlaufen von Frames nach einer Hotspot-Aktion.
  • timerMutations Timer starten, pausieren, fortsetzen, umschalten, zurücksetzen, stoppen oder die Dauer ändern.
  • patches JSON-State mittels Literalwerten, Templates, Timestamps, Inkrementen, Toggles oder Unset-Operationen aktualisieren.
  • hotspots Tap-Bereiche auf Action-IDs mappen.
  • listTemplateEvents Ermöglicht der App, von Widgets ausgehende Aktionen verzögert zu verarbeiten.

Die Runtime löst Platzhalter wie {{state.title}}, {{timers.rest.remainingText}}, und {{meta.template.kind}} auf, bevor der Native Bridge eine Surface zum Rendern zurückgibt.

Full-native Sessions sind für Widgets gedacht, die ihr UI nativ rendern:

  • startWidgetSession erstellt Shared State und Metadaten für das native Widget code.
  • updateWidgetSession mergt oder ersetzt den State und markiert die Session wieder als aktiv.
  • stopWidgetSession zeichnet den finalen State auf und markiert die Session als gestoppt.
  • sendWidgetMessage stellt App-zu-Widget oder Widget-zu-App Aufgaben in eine Queue.
  • acknowledgeWidgetMessages markiert Nachrichten als empfangen.
  • completeWidgetMessage speichert eine Antwort oder einen Fehler für Async-Jobs.

Nachrichten sind nach Abschluss idempotent: Ein Retry einer abgeschlossenen oder fehlgeschlagenen Nachricht liefert das bestehende Ergebnis, statt es zu überschreiben.

MethodeBeschreibung
areActivitiesSupportedPrüfen, ob die native Template Activity Bridge auf dem aktuellen Gerät laufen kann.
startTemplateActivityEine SVG Template Activity persistieren und die native Live Activity Bridge starten.
updateTemplateActivityDie Activity-Definition, den State oder die URL zum Öffnen ersetzen.
endTemplateActivityEine laufende Activity beenden und optional einen letzten State-Snapshot speichern.
performTemplateActionDeklarative Patches, Frame-Mutationen, Timer-Mutationen und Event-Logging ausführen.
getTemplateActivityEine gespeicherte Template Activity auslesen.
listTemplateActivitiesAlle gespeicherten Template Activities auflisten.
listTemplateEventsAction-Events auslesen, die von Template-Actions emittiert wurden.
acknowledgeTemplateEventsTemplate-Events als verarbeitet markieren.
startWidgetSessionEine native Widget-Session starten, die auf einem gemeinsamen JSON-State basiert.
updateWidgetSessionDen State einer nativen Widget-Session mergen oder ersetzen.
stopWidgetSessionEine native Widget-Session stoppen und optional den finalen State speichern.
getWidgetSessionEine vollständig native Widget-Session lesen.
listWidgetSessionsAlle vollständig nativen Widget-Sessions auflisten.
sendWidgetMessageNachrichten zwischen der App und dem nativen code Widget in eine Queue einreihen.
listWidgetMessagesBridge-Nachrichten in der Queue auflisten.
acknowledgeWidgetMessagesBridge-Nachrichten als bestätigt markieren.
completeWidgetMessageComplete or fail an async bridge message.
getPluginVersionDen Versionsmarker der Plattform-Implementierung zurückgeben.

Das Plugin enthält zudem native Helfer für Widget-Targets:

  • CapgoTemplateWidgetBridge löst eine SVG-Template-Oberfläche in svg, frameId, hotspots, und Metadaten auf.
  • CapgoTemplateActionIntent verbindet interaktive iOS-Widget-Buttons mit Template-Aktionen.
  • CapgoNativeWidgetBridge lädt native Sessions und Nachrichten aus dem nativen Widget code.
  • Android-Template-Helper bieten passendes Verhalten für Action Receiver und Widget Bridge.

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

Wenn du es nutzt @capgo/capacitor-widget-kit um CI/CD-Automatisierung zu planen, verbinde es mit @capgo/capacitor-widget-kit verwenden für die native Funktion in „@capgo/capacitor-widget-kit verwenden“, Capgo CI/CD für den Produkt-Workflow in Capgo CI/CD, Capgo Native Builds optimieren für den Produkt-Workflow in Capgo Native Builds, Capgo Integrationen für den Produkt-Workflow in Capgo Integrationen, und CI/CD-Integration für das Implementierungsdetail in der CI/CD-Integration.