@capgo/capacitor-widget-kit

Übersicht

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.

Plattformunterstützung

Plattform	Support	Notizen
iOS	Ja	Nativ
Android	Ja	Nativ
Web	Nein	Absichern mit Capacitor.getPlatform()

Siri, Shortcuts und App Intents

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

Es deckt 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.

Demo

Widget-Template-Flow

Modus wählen

Modus	Ideal für	Haupt-APIs
SVG-Template-Activity	Live Activities oder Widget-Oberflächen, die aus SVG-Output gerendert werden	startTemplateActivity, performTemplateAction, listTemplateEvents
Full-Native-Widget-Session	Nativ gerenderte Widgets, die Shared State und Async-Jobs brauchen	startWidgetSession, 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-Template-Funktionen

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 später 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-Bridge-Funktionen

Full-native Sessions sind für Widgets gedacht, die ihr eigenes 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 Response 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.

Öffentliches API

Methode	Beschreibung
areActivitiesSupported	Prüfen, ob die native Template-Activity-Bridge auf dem aktuellen Gerät laufen kann.
startTemplateActivity	Eine SVG-Template-Activity persistieren und die native Live Activity Bridge starten.
updateTemplateActivity	Die Activity-Definition, den State oder die URL ändern.
endTemplateActivity	Eine laufende Activity beenden und optional einen letzten State-Snapshot speichern.
performTemplateAction	Deklarative Patches, Frame-Mutationen, Timer-Mutationen und Event-Logging ausführen.
getTemplateActivity	Eine gespeicherte Template-Activity auslesen.
listTemplateActivities	Alle gespeicherten Template-Activities auflisten.
listTemplateEvents	Action-Events auslesen, die von Template-Actions ausgelöst wurden.
acknowledgeTemplateEvents	Template-Events als verarbeitet markieren.
startWidgetSession	Eine native Widget-Session mit gemeinsamem JSON-State starten.
updateWidgetSession	Den State einer nativen Widget-Session mergen oder ersetzen.
stopWidgetSession	Eine native Widget-Session stoppen und optional den finalen State speichern.
getWidgetSession	Eine vollständig native Widget-Session lesen.
listWidgetSessions	Alle vollständig nativen Widget-Sessions auflisten.
sendWidgetMessage	Nachrichten zwischen der App und dem nativen code Widget in eine Queue einreihen.
listWidgetMessages	Bridge-Nachrichten in der Queue auflisten.
acknowledgeWidgetMessages	Bridge-Nachrichten als bestätigt markieren.
completeWidgetMessage	Complete or fail an async bridge message.
getPluginVersion	Den Versionsmarker der Plattform-Implementierung zurückgeben.

Native Bausteine

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.

Source of Truth

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

Weiter mit @capgo/capacitor-widget-kit

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.