@capgo/capacitor-kit-de-widgets

Vue d'ensemble

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

• Activités de modèles SVG : définir les surfaces de WidgetKit en tant que SVG, passer des cadres nommés à partir de touches, exécuter des temporisations pause/lecture, muter l'état JSON et collecter les événements d'action dans l'application.
• Séances de widgets natifs complètes : garder 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 séances 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.

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 workout peut utiliser une activité SVG Live pour des contrôles de cadence rapide/timer et une session de widget natif complet pour un widget d'écran d'accueil avec une disposition native plus riche.

Capacités de modèles SVG

des variantes de modèles SVG nommées comme

• frames ou summary, timerune case à cocher, un bouton, ou passer d'une image à l'autre après une action sur un hotspot. details.
• frameMutations lancer, arrêter, reprendre, activer/désactiver, réinitialiser, arrêter ou modifier la durée du timer.
• timerMutations mettre à jour l'état JSON à l'aide de valeurs littérales, de modèles, de timestamps, d'incréments, de cases à cocher ou d'opérations d'annulation.
• patches associer des zones de tap à des identifiants d'action.
• hotspots permet à l'application de traiter les actions provenant du widget plus tard.
• listTemplateEvents La runtime remplace les marqueurs comme __CAPGO_KEEP_0__

Les modèles SVG incluent les pièces nécessaires pour les surfaces de widgets interactifs : {{state.title}}, {{timers.rest.remainingText}}et {{meta.template.kind}} avant que le pont natif ne renvoie une surface de 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 partagé et des métadonnées 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 exécution : réessayer 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'ouverture d'une URL.
endTemplateActivity	Terminez une activité en cours et persistez éventuellement une dernière capture d'état.
performTemplateAction	Exécutez des patchs déclaratifs, des mutations de cadre, des mutations de temporisation et des enregistrements 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	Démarrer une session de widget natif complet avec un état partagé JSON.
updateWidgetSession	Fusionner ou remplacer l'état de session de widget natif complet.
stopWidgetSession	Arrêter une session de widget natif complet et conserver l'état final facultativement.
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	Retourner la marque de version de l'implémentation de 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 en résolvant svg, frameId, hotspots, et des 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 de widget code.
• Les aides 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 de src/definitions.ts dans le référentiel du plugin.

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

Si vous utilisez @capgo/capacitor-kit-de-widgets pour planifier l'automatisation CI/CD, connectez-le à En utilisant @capgo/capacitor-kit-de-widgets pour la capacité native dans En utilisant @capgo/capacitor-kit-de-widgets, 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 pour le flux de travail du produit dans Capgo Intégrations, et Intégration CI/CD pour les détails d'implémentation dans l'intégration CI/CD.