Übersicht
Abschnitt mit dem Titel „Übersicht“@capgo/capacitor-widget-kit gibt einem 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 Pause-/Wiedergabe-Timer, ändern Sie JSON-Zustand und sammeln Sie Ereignisse in der App.
- Vollnativer 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 renderbar ist. Verwenden Sie voll-native Sitzungen, wenn das Widget eine benutzerdefinierte native Benutzeroberfläche benötigt, aber immer noch starten, stoppen, den Zustand synchronisieren oder die Anwendung um asynche Arbeit bitten muss.
Wählen Sie eine Modus
Modus| Am besten für | Haupt-APIs | SVG-Vorlagenaktivität |
|---|---|---|
| Live-Aktivitäten oder Widgetoberflächen, die aus SVG-Ausgaben renderen | Voll-native Widget-Sitzung | startTemplateActivity, performTemplateAction, listTemplateEvents |
| Widgets, die native renderen und gemeinsamen Zustand und asynche Aufgaben benötigen | Beide Modi können in derselben App coexistieren. Zum Beispiel kann ein Workout-App ein SVG-Live-Aktivität für schnelle Frame/Zählersteuerung und eine voll-native Widget-Sitzung für eine Home-Screen-Widget mit einer reicheren native Layout verwenden. | startWidgetSession, updateWidgetSession, sendWidgetMessage |
SVG-Vorlagenfunktionen
Choose A Mode
Abschnitt mit dem Titel „SVG-Template-Fähigkeiten”SVG-Vorlagen enthalten die notwendigen Teile für interaktive Widgetoberflächen:
framesHaltbare SVG-Varianten wiesummary,timer, oderdetails.frameMutationsSchaltfläche, Schalter, oder durch Frames nach einem Hotspot-Aktion schalten.timerMutationsStarten, pausieren, fortsetzen, schalten, zurücksetzen, stoppen oder die Timerdauer ändern.patchesAktualisieren Sie den JSON-Zustand mit Literalwerten, Mustern, Zeitstempeln, Inkrementen, Schaltern oder Unset-Operationen.hotspotsMappen Sie Berührungsbereiche auf Aktionenidentifikatoren.listTemplateEventsLassen Sie das App-Verfahren die von Widgets ausgelösten Aktionen später ausführen.
Die Laufzeit löst Platzhalter wie {{state.title}}, {{timers.rest.remainingText}}, und {{meta.template.kind}} vor der nativen Brücke zurückgibt, bevor eine Oberfläche für das Rendering bereitgestellt wird.
Voll-Native-Bridge-Fähigkeiten
Abschnitt mit dem Titel „Voll-Native-Bridge-Fähigkeiten”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.stopWidgetSessionrekordiert einen letzten Zustand und markiert die Sitzung als gestoppt.sendWidgetMessagewirkt App-zu-Widget- oder Widget-zu-App-Aufgaben ab.acknowledgeWidgetMessagesmarkiert Nachrichten als empfangen.completeWidgetMessagespeichert 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.
Öffentliches API
Abschnitt mit dem Titel „Öffentliches 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 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ändige native Widget-Sitzung, die durch gemeinsam verwendete JSON-Zustände unterstützt wird. |
updateWidgetSession | Mergen oder ersetzen Sie einen vollständigen nativen Widget-Sitzungsstatus. |
stopWidgetSession | Beenden Sie eine vollständige nativere Widget-Sitzung und speichern Sie optional den finalen Status. |
getWidgetSession | Lesen Sie eine vollständige nativere Widget-Sitzung. |
listWidgetSessions | Listen Sie alle vollständigen nativen Widget-Sitzungen. |
sendWidgetMessage | Warten Sie auf eine Nachricht zwischen der App und dem nativen Widget code. |
listWidgetMessages | Listen Sie die in der Warteschleife stehenden Bridge-Nachrichten. |
acknowledgeWidgetMessages | Melden Sie Bridge-Nachrichten als bestätigt. |
completeWidgetMessage | Erledigen Sie oder feiern Sie einen asynchronen Bridge-Nachrichten. |
getPluginVersion | Rufen Sie die Versionsmarke der Plattformimplementierung ab. |
Nativstücke
Abschnitt mit dem Titel “Nativstücke”Das Plugin liefert auch native Hilfsfunktionen für Zielwidgete:
CapgoTemplateWidgetBridgelöst eine SVG-Vorlageoberfläche aufsvg,frameId,hotspots, und Metadaten.CapgoTemplateActionIntentVerbindet interaktive iOS-Widget-Buttons mit Vorlagenvorgängen.CapgoNativeWidgetBridgeLädt vollständige native Sitzungen und Nachrichten von native Widgeten code.- Android-Vorlagenhilfen bieten übereinstimmendes Aktionsempfänger- und Widgetbrücke-Verhalten.
Quelle der Wahrheit
Abschnitt mit dem Titel „Quelle der Wahrheit“Die API-Referenz wird von src/definitions.ts im Plugin-Repository.