@capgo/capacitor-kit de widgets

Présentation

@capgo/capacitor-widget-kit donne à une application Capacitor deux façons de faire fonctionner les widgets et les activités en direct :

• Activités de modèles SVG : définissez les surfaces du kit de widgets en tant que SVG, passez entre les cadres nommés à partir des appuis, exécutez les temporisations pause/jeu, modifiez l'état JSON et collectez les événements d'action dans l'application.
• Sessions de widgets natifs complets : maintenez l'interface utilisateur du widget complètement en Swift/Kotlin/Java tandis que Capacitor possède l'état JSON partagé et les messages app-à-widget ou widget-à-app.

Utilisez les modèles SVG lorsque votre widget peut être rendu à partir de chaînes de SVG résolues. Utilisez les sessions de widgets natifs complètes lorsque le widget nécessite une interface utilisateur native personnalisée mais doit toujours démarrer, arrêter, synchroniser l'état ou demander à l'application de terminer le travail asynchrone.

Choisissez un mode

Mode	Meilleur pour	API principales
Modèle d'activité SVG	Activités en direct ou surfaces de widget qui rendent à partir de la sortie SVG	startTemplateActivity, performTemplateAction, listTemplateEvents
Session de widget natif intégral	Widgets rendus nativement qui nécessitent un état partagé et des tâches asynchrones	startWidgetSession, updateWidgetSession, sendWidgetMessage

Les deux modes peuvent coexister dans la même application. Par exemple, une application de workout peut utiliser une activité SVG en direct pour des contrôles de cadence rapide/timer et une session de widget natif intégral pour un widget d'écran d'accueil avec un affichage natif plus riche.

Capacités du modèle SVG

Les modèles SVG incluent les pièces nécessaires pour les surfaces de widgets interactifs :

• frames tels que les variantes SVG nommées summary, timer, ou details.
• frameMutations passer d'une étape à l'autre après une action sur un hotspot.
• timerMutations démarrer, mettre en pause, reprendre, activer/désactiver, réinitialiser, arrêter ou modifier la durée du chronomètre.
• patches mettre à jour l'état JSON en utilisant des valeurs littérales, des modèles, des horodatages, des incréments, des commutateurs ou des opérations d'annulation.
• hotspots associer les zones de tap à des identifiants d'action.
• listTemplateEvents permet à l'application de traiter les actions provenant des widgets plus tard.

Le runtime remplace les marqueurs comme {{state.title}}, {{timers.rest.remainingText}}, et {{meta.template.kind}} avant que le pont natif ne retourne une surface pour la rendu.

Capacités du Pont Natif Complet

Les sessions natives sont pour les widgets qui rendent leur propre interface utilisateur de manière native :

• startWidgetSession crée un état et des métadonnées partagés pour le widget natif code.
• updateWidgetSession fusionne ou remplace l'état et marque la session active à nouveau.
• stopWidgetSession enregistre un état final et marque la session arrêtée.
• sendWidgetMessage file les tâches app-à-widget ou widget-à-app.
• acknowledgeWidgetMessages marque les messages comme reçus.
• completeWidgetMessage stocke une réponse ou un échec pour les tâches asynchrones.

Les messages sont idempotents après la fin : une tentative de relecture d'un message terminé ou échoué renvoie le résultat existant au lieu de l'effacer.

Public API

Méthode	Description
areActivitiesSupported	Vérifiez si le pont d'activité de modèle natif peut s'exécuter sur le dispositif actuel.
startTemplateActivity	Persiste un modèle d'activité SVG et démarrez le pont d'activité Live natif.
updateTemplateActivity	Remplacez la définition d'activité, l'état ou l'URL ouverte.
endTemplateActivity	Terminez une activité en cours et persistez optionnellement un dernier instantané d'état.
performTemplateAction	Exécutez des correctifs déclaratifs, des mutations de cadre, des mutations de temporisation et des journaux d'événements.
getTemplateActivity	Lisez un modèle d'activité stocké.
listTemplateActivities	Listez tous les modèles d'activité stockés.
listTemplateEvents	Lisez les événements d'action émis par les actions de modèle.
acknowledgeTemplateEvents	Marquez les événements de modèle comme traités.
startWidgetSession	Démarrez une session de widget natif complète basée sur un état partagé en JSON.
updateWidgetSession	Faites fusionner ou remplacer l'état d'une session de widget natif complète.
stopWidgetSession	Arrêter une session de widget natif complet et conserver l'état final si nécessaire.
getWidgetSession	Lire une session de widget natif complet.
listWidgetSessions	Lister toutes les sessions de widget natif complet.
sendWidgetMessage	Enfile une message entre l'application et le widget natif code.
listWidgetMessages	Lister les messages de pont en attente.
acknowledgeWidgetMessages	Marquer les messages de pont comme reconnus.
completeWidgetMessage	Terminer ou échouer un message de pont asynchrone.
getPluginVersion	Renvoyer la marque de version de l'implémentation de la plateforme.

Pièces natives

Le plugin embarque également des aides natives pour les cibles de widget :

• CapgoTemplateWidgetBridge résout une surface de modèle SVG svg, frameId, hotspots, et les métadonnées.
• CapgoTemplateActionIntent connecte les boutons d'interface iOS interactifs aux actions de modèle.
• CapgoNativeWidgetBridge charge les sessions et les messages natives complets à partir du widget natif code.
• Les helpers de modèle Android fournissent un comportement de réception d'action et de pont de widget correspondant.

Source De Vérité

La référence API est synchronisée à partir du src/definitions.ts dans le référentiel de plugin.