@capgo/capacitor-kit-de-widget

Vue d'ensemble

@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 sous forme de SVG, passer entre les vignettes nommées à partir des appuis, exécuter les temporisations pause/lecture, modifier l'état JSON et collecter les événements d'action dans l'application.
• Séances de widgets natives intégrales : garder 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.

Use SVG templates when your widget can be rendered from resolved SVG strings. Use full-native sessions when the widget needs a custom native UI but still has to start, stop, sync state, or ask the app to complete async work.

Demo

Flux de modèle de widget

Sélectionner un mode

Mode	Idéal pour	API principaux
Activité de modèle SVG	Activités ou surfaces de widget qui affichent à partir de la sortie SVG	startTemplateActivity, performTemplateAction, listTemplateEvents
Session de widget natif complète	Widgets nativement affichés 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 cadre/timer rapides et une session de widget natif complète pour un widget d'écran d'accueil avec une mise en page native plus riche.

Capacités de modèle SVG

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

• frames tenir des variantes de SVG nommées telles que summary, timer, ou details.
• frameMutations Passer d'une frame à l'autre après une action de hotspot.
• timerMutations start, pause, resume, toggle, reset, stop, or change timer duration.
• patches update JSON state using literal values, templates, timestamps, increments, toggles, or unset operations.
• hotspots associer des zones de tap à des identifiants d'action.
• listTemplateEvents permet à l'application de traiter les actions provenant des widgets plus tard.

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 la rendu.

Capacités du Pont Natif Complet

Les sessions natives sont réservées aux widgets qui rendent leur 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 dernier état et marque la session arrêtée.
• sendWidgetMessage queues app-to-widget or widget-to-app work.
• 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 leur terminaison : réessayer un message terminé ou échoué renvoie le résultat existant au lieu de l'effacer.

Zone publique API

Méthode	Description
areActivitiesSupported	Vérifiez si le pont d'activité de template natif peut fonctionner sur le dispositif actuel.
startTemplateActivity	Persister un modèle SVG d'activité 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 conserver éventuellement un dernier instantané d'état.
performTemplateAction	Exécuter des patchs 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	Commencez une session de widget natif intégral alimentée par 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 éventuellement l'état final.
getWidgetSession	Lire une session de widget natif complète.
listWidgetSessions	Lister toutes les sessions de widgets natifs complets.
sendWidgetMessage	Filez un message entre l'application et le widget natif code.
listWidgetMessages	Liste de messages de pont en attente.
acknowledgeWidgetMessages	Marquer les messages de pont comme reconnus.
completeWidgetMessage	Terminer ou échouer un message de pont asynchrone.
getPluginVersion	Rendre 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 widgets :

• CapgoTemplateWidgetBridge résout une surface de modèle SVG en svg, frameId, hotspotset des métadonnées.
• CapgoTemplateActionIntent connecte les boutons de widget 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èl’Android fournissent un comportement de récepteur d'action et de pont de widget correspondant.

Source De Vérité

La référence au API est synchronisée à partir src/definitions.ts du 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 CI/CD, connectez-l’avec En utilisant @capgo/capacitor-kit-de-widget pour la capacité native dans l'utilisation de @capgo/capacitor-widget-kit, 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 le détail d'implémentation dans Intégration CI/CD.