@capgo/capacitor-kit de widgets

Vue d'ensemble

@capgo/capacitor-widget-kit offre à une application Capacitor deux façons de contrôler les widgets et les activités en direct :

• Activités de modèles SVG : définissez les surfaces de WidgetKit en tant qu'SVG, passez des cadres nommés à partir des touches, exécutez des temporisations pause/jeu, modifiez l'état JSON et collectez les événements d'action dans l'application.
• Séances 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 d'SVG résolues. Utilisez les séances de widgets 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.

Choisissez un Mode

Mode	Meilleur pour	Fonctions principales
Activité de modèle SVG	Activités en direct ou surfaces de widgets qui rendent à partir de sortie SVG	startTemplateActivity, performTemplateAction, listTemplateEvents
Séance de widget native intégrale	Widgets natifs rendus 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 complet 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, timer, ou details.
• frameMutations permettre de 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 timer.
• 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 les zones de tap à des identifiants d'action.
• listTemplateEvents permet à l'application de traiter les actions provenant du widget plus tard.

The runtime résout les placeholders comme __CAPGO_KEEP_0__ {{state.title}}, {{timers.rest.remainingText}}, et {{meta.template.kind}} avant que le pont natif 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 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 dernier état 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é 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 périphérique actuel.
startTemplateActivity	Persister un modèle d'activité SVG et démarrer le pont de Live Activity natif.
updateTemplateActivity	Remplacer la définition d'activité, l'état ou l'URL ouverte.
endTemplateActivity	Terminer une activité en cours et persister optionnellement un dernier instantané d'état.
performTemplateAction	Exécuter des correctifs déclaratifs, des mutations de cadre, des mutations de temporisateur et des journaux d'événements.
getTemplateActivity	Lire une activité de modèle stockée.
listTemplateActivities	Lister toutes les activités de modèle stockées.
listTemplateEvents	Lire 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 plein écran basée sur un état JSON partagé.
updateWidgetSession	Fusionner ou remplacer l'état d'une session de widget natif plein écran.
stopWidgetSession	Arrêter une session de widget natif plein écran et conserver l'état final si nécessaire.
getWidgetSession	Lire une session de widget natif plein écran.
listWidgetSessions	Lister toutes les sessions de widget natif plein écran.
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 fournit également des aides natives pour les cibles de widget :

• CapgoTemplateWidgetBridge résout une surface de modèle SVG en __CAPGO_KEEP_0__ svg, frameId, hotspots, et les métadonnées.
• CapgoTemplateActionIntent connecte les boutons de widget iOS interactifs à des actions de modèle.
• CapgoNativeWidgetBridge charge des sessions et des messages natives complets à partir du 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 src/definitions.ts du référentiel du plugin.