@capgo/capacitor-kit-de-widgets

Aperçu

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

• Activités de modèles SVG : définir les surfaces WidgetKit en tant qu'SVG, passer des vignettes nommées de clics, exécuter des temporisations pause/jeu, muter l'état JSON et collecter les événements d'action dans l'application.
• Sessions de widgets natives intégrales : garder l'interface utilisateur du widget entièrement 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 résolution SVG. 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

Choisissez un mode

Mode	Meilleur pour	API principaux
Activité de modèle SVG	Activités ou surfaces de widget qui rendent à partir de l'output 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 séance de widget native complète 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 désignent des variantes SVG nommées comme 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 à 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 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 à Pleine Puissance

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 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 exécution : une tentative de 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	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 une dernière capture d'état.
performTemplateAction	Exécutez des correctifs déclaratifs, des mutations de cadre, des mutations de temporisation et des enregistrements 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 remplacerz l'état d'une session de widget natif complète.
stopWidgetSession	Arrêtez une session complète de widget natif et persistez éventuellement l'état final.
getWidgetSession	Lisez une session complète de widget natif.
listWidgetSessions	Listez toutes les sessions de widget natif.
sendWidgetMessage	Filez un message entre l'application et le widget natif code.
listWidgetMessages	Listez les messages de pont en attente.
acknowledgeWidgetMessages	Marquez les messages de pont comme reconnus.
completeWidgetMessage	Terminez ou échouez un message de pont asynchrone.
getPluginVersion	Retournez la marque de version de l'implémentation de la plateforme.

Pieces 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, hotspotset les métadonnées.
• CapgoTemplateActionIntent connecte les boutons d'interface iOS widget à des actions de modèle.
• CapgoNativeWidgetBridge charge des sessions et des messages full-native à 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 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-widget pour planifier l'automatisation de 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 de CI/CD pour le détail d'implémentation dans Intégration de CI/CD.