@capgo/capacitor-widget-kit

Aperçu

Créez des surfaces WidgetKit et Live Activity depuis Capacitor avec des cadres SVG, des minuteurs, des hotspots d'action ou une synchronisation d'état de widget 100 % natif

Commencez par areActivitiesSupported() et les autres méthodes principales listées ci-dessous.

Support des plateformes

Plateforme	Support	Notes
iOS	Oui	Natif
Android	Oui	Natif
Le Web	Non	Protéger avec Capacitor.getPlatform()

Siri, Shortcuts et App Intents

Widget Kit est pas une passerelle Siri ou Shortcuts. Il prend en charge WidgetKit, les modèles ActivityKit pour les Live Activities, et les contrôles iOS interactifs via des types LiveActivityIntent groupés (CapgoTemplateActionIntent, CompleteSetIntent) qui mettent à jour l'état du modèle stocké et ajoutent à l' event log (listTemplateEvents / acknowledgeTemplateEvents).

Il permet de pas register custom shortcut phrases, AppShortcutsProvider, des catalogues d'entités JavaScript, des éléments Spotlight ou des schémas d'app Apple. Utilisez @capgo/capacitor-app-intents pour cela. Pour une comparaison complète avec des outils comme expo-app-intents, consultez Siri, Raccourcis et widgets.

Démo

Flux de templates de widget

Choisir un mode

Mode	Idéal pour	Principales API
Activité via template SVG	Live Activities ou surfaces de widgets rendues à partir d'un rendu SVG	startTemplateActivity, performTemplateAction, listTemplateEvents
Session de widget full-native	Widgets rendus nativement nécessitant 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 Live Activity SVG pour des contrôles rapides de timer/cadence, et une session de widget full-native pour un widget d'écran d'accueil avec une mise en page native plus riche.

Capacités du template SVG

Les templates SVG incluent les éléments nécessaires aux surfaces de widgets interactives :

• frames contient des variantes SVG nommées telles que summary, timer, ou details.
• frameMutations switch, toggle, ou pour parcourir les frames après une action sur un hotspot.
• timerMutations démarrer, mettre en pause, reprendre, basculer, réinitialiser, arrêter ou modifier la durée du timer.
• patches mettre à jour l'état JSON à l'aide de valeurs littérales, de templates, d'horodatages, d'incréments, de bascules ou d'opérations de suppression.
• hotspots mapper les zones de tap aux identifiants d'action.
• listTemplateEvents permet à l'app de traiter ultérieurement les actions provenant des widgets.

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

Capacités complètes du bridge natif

Les sessions full-native sont destinées aux widgets qui génèrent leur propre interface 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 à nouveau la session comme active.
• stopWidgetSession enregistre un état final et marque la session comme arrêtée.
• sendWidgetMessage met en file d'attente les tâches entre l'app et le widget.
• acknowledgeWidgetMessages marque les messages comme reçus.
• completeWidgetMessage stocke une réponse ou un échec pour les jobs asynchrones.

Les messages sont idempotents une fois terminés : réessayer un message terminé ou échoué renvoie le résultat existant au lieu de l'écraser.

API public

Méthode	Description
areActivitiesSupported	Vérifiez si le bridge de l'activité du template natif peut s'exécuter sur l'appareil actuel.
startTemplateActivity	Persistez une activité de template SVG et lancez le bridge natif de Live Activity.
updateTemplateActivity	Remplacez la définition de l'activité, l'état ou l'URL d'ouverture.
endTemplateActivity	Terminez une activité en cours et, optionnellement, persistez un dernier snapshot de l'état.
performTemplateAction	Exécutez des patches déclaratifs, des mutations de frames, des mutations de timers et le logging d'événements.
getTemplateActivity	Lisez une activité de template stockée.
listTemplateActivities	Listez toutes les activités de template stockées.
listTemplateEvents	Lisez les événements d'action émis par les actions du template.
acknowledgeTemplateEvents	Marquez les événements du template comme traités.
startWidgetSession	Démarrez une session de widget full-native basée sur un état JSON partagé.
updateWidgetSession	Fusionnez ou remplacez l'état d'une session de widget full-native.
stopWidgetSession	Arrêtez une session de widget full-native et, optionnellement, persistez l'état final.
getWidgetSession	Lire une session de widget full-native.
listWidgetSessions	Lister toutes les sessions de widget full-native.
sendWidgetMessage	Mettez en file d'attente un message entre l'application et le widget natif code.
listWidgetMessages	Liste les messages de bridge en attente.
acknowledgeWidgetMessages	Marquer les messages du bridge comme acquittés.
completeWidgetMessage	Terminer ou échouer un message de bridge asynchrone.
getPluginVersion	Retourne l'indicateur de version de l'implémentation de la plateforme.

Native Pieces

Le plugin fournit également des helpers natifs pour les cibles de widget :

• CapgoTemplateWidgetBridge résout une surface de template SVG en svg, frameId, hotspots, et les métadonnées.
• CapgoTemplateActionIntent connecte les boutons de widgets iOS interactifs aux actions de template.
• CapgoNativeWidgetBridge charge les sessions et messages full-native depuis le widget natif code.
• Les helpers de templates Android fournissent un action receiver et un comportement de widget bridge équivalents.

Source de vérité

La référence API est synchronisée depuis src/definitions.ts dans le dépôt du plugin.

Pour aller plus loin avec @capgo/capacitor-widget-kit

Si vous utilisez @capgo/capacitor-widget-kit pour planifier l'automatisation CI/CD, et le connecter avec Utiliser @capgo/capacitor-widget-kit pour la capacité native dans l'utilisation de @capgo/capacitor-widget-kit, CI/CD Capgo pour le workflow produit dans le CI/CD de Capgo, Capgo Native Build pour le workflow produit dans les Native Builds de Capgo, Intégrations Capgo pour le workflow produit dans les intégrations Capgo, et Intégration CI/CD pour le détail d'implémentation dans l'intégration CI/CD.