@capgo/capacitor-widget-kit

Vue d'ensemble

@capgo/capacitor-widget-kit fournit à 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 modèles SVG, passez entre les vignettes nommées à partir des touches, exécutez les temporisations d'arrêt/démarrage, modifiez l'état JSON et collectez les événements d'action dans l'application.
• Sessions de widgets natives intégrales : maintenez l'interface utilisateur du widget entièrement en Swift/Kotlin/Java tandis que Capacitor gère 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 modèles SVG résolus. Utilisez les sessions natives intégrales 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.

Démonstration

Flux de modèle de widget

Sélectionner un mode

Mode	Meilleur pour	API principaux
Activité de modèle SVG	Activités en direct ou surfaces de widget qui affichent à partir de la sortie SVG	startTemplateActivity, performTemplateAction, listTemplateEvents
Séance de widget native complète	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 fitness peut utiliser une activité SVG Live pour des contrôles de frame/timer rapides et une session de widget natif complète pour un widget d'écran d'accueil avec une disposition native plus riche.

Capacités de modèles SVG

Les modèles SVG incluent les pièces nécessaires pour les surfaces de widget interactives :

• frames des variantes de SVG nommées telles que summary, timerou details.
• frameMutations passer d'une étape à l'autre après une action sur un hotspot.
• timerMutations lancer, arrêter, reprendre, activer/désactiver, réinitialiser ou modifier la durée du chronomètre.
• patches mettre à jour l'état JSON à l'aide de valeurs littérales, de modèles, de timestamps, d'incréments, de toggles ou d'opérations d'annulation.
• hotspots associer des zones de tap à des identifiants d'action.
• listTemplateEvents permet à l'application de traiter les actions provenant du widget ultérieurement.

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

Capacités du Pont Natif Complet

Les sessions natives complètes sont pour les widgets qui rendent leur propre interface utilisateur nativement :

• 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 : la reprise d'un message terminé ou échoué retourne 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	Persistez un modèle d'activité SVG et démarrez le pont de Live Activity natif.
updateTemplateActivity	Remplacez la définition d'activité, l'état ou l'URL ouverte.
endTemplateActivity	Terminez une activité en cours et persistez éventuellement un dernier instantané d'état.
performTemplateAction	Exécutez des patchs déclaratifs, des mutations de cadre, des mutations de temporisateur et des journaux d'événements.
getTemplateActivity	Lisez une activité de modèle stockée.
listTemplateActivities	Listez toutes les activités de modèle stockées.
listTemplateEvents	Lisez les événements d'action émis par les actions de modèle.
acknowledgeTemplateEvents	Marquer les événements de modèle comme traités.
startWidgetSession	Lancer une session de widget natif complète basée sur un état JSON partagé.
updateWidgetSession	Fusionner ou remplacer l'état d'une session de widget natif complète.
stopWidgetSession	Arrêter une session de widget natif complète et conserver l'état final si nécessaire.
getWidgetSession	Lire une session de widget natif complète.
listWidgetSessions	Lister toutes les sessions de widget natif complètes.
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	Récupérer la marque de version de l'implémentation du système d'exploitation.

Pièces natives

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

• CapgoTemplateWidgetBridge résout une surface de modèle SVG en pièces natives svg, frameId, hotspots, et les métadonnées.
• CapgoTemplateActionIntent connecte les boutons de widget interactifs iOS à des actions de modèle.
• CapgoNativeWidgetBridge charge des sessions et des messages natives complets à partir du widget code.
• Les aides de modèl’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 du plugin.

Continuez à partir de @capgo/capacitor-widget-kit

Si vous utilisez @capgo/capacitor-kit de widget pour planifier l'automatisation CI/CD, connectez-l’avec Utilisez @capgo/capacitor-kit de widget pour la capacité native dans Utilisez @capgo/capacitor-kit de widget, Capgo CI/CD pour le flux de travail du produit dans Capgo CI/CD, Capgo Builds natifs pour le flux de travail du produit dans Capgo Builds natifs, Capgo Intégrations for the product workflow in Capgo Integrations, and Intégration CI/CD pour les détails d'implémentation dans l'intégration CI/CD