Getting Started

Section intitulée « Installer »

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Utilisez ensuite la commande suivante :

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-widget-kit` plugin in my project.

Si vous préférez la configuration manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à la plateforme ci-dessous :

bun add @capgo/capacitor-widget-kit
bunx cap sync

Importer

import { CapgoWidgetKit } from '@capgo/capacitor-widget-kit';

Configuration iOS

Pour les activités en direct et les extensions de WidgetKit, configurez l'application native en premier :

• Utilisez iOS 17+ pour les boutons d'activité en direct interactifs lorsqu'il est possible.
• Ajoutez NSSupportsLiveActivities à l'application Info.plist lorsque vous utilisez ActivityKit.
• Ajoutez le même groupe d'application à la cible de l'application et à la cible de l'extension de widget.
• Définissez CapgoWidgetKitAppGroup dans les deux Info.plist fichiers sur l'identifiant du groupe d'application partagé.

<key>CapgoWidgetKitAppGroup</key>
<string>group.app.capgo.widgetkit.exampleapp.widgetkit</string>

Vérifiez le Support

const { supported, reason } = await CapgoWidgetKit.areActivitiesSupported();

if (!supported) {
  console.log('WidgetKit bridge unavailable:', reason);
}

Option 1 : Modèle SVG d'activité

Utilisez ce mode lorsque le widget peut afficher l'SVG résolu. Le plugin stocke l'état, remplace les marqueurs, applique les actions de tap, change les vignettes SVG et maintient l'état du chronomètre cohérent.

const { activity } = await CapgoWidgetKit.startTemplateActivity({
  activityId: 'workout-session-1',
  openUrl: 'myapp://workout/session-1',
  state: {
    title: 'Chest Day',
    frame: 'summary',
    restDurationMs: 90000,
  },
  definition: {
    id: 'workout-card',
    timers: [
      {
        id: 'rest',
        durationPath: 'state.restDurationMs',
      },
    ],
    actions: [
      {
        id: 'next-frame',
        eventName: 'widget.frame.changed',
        frameMutations: [
          {
            op: 'next',
            path: 'frame',
            surface: 'lockScreen',
          },
        ],
      },
      {
        id: 'toggle-rest',
        eventName: 'widget.timer.toggled',
        timerMutations: [
          {
            op: 'toggle',
            timerId: 'rest',
          },
        ],
      },
    ],
    layouts: {
      lockScreen: {
        width: 100,
        height: 40,
        frameIdPath: 'state.frame',
        frames: [
          {
            id: 'summary',
            hotspots: [{ id: 'switch', actionId: 'next-frame', x: 0, y: 0, width: 100, height: 40 }],
            svg: `<svg viewBox="0 0 100 40"><text x="6" y="22">{{state.title}}</text></svg>`,
          },
          {
            id: 'timer',
            hotspots: [{ id: 'pause-play', actionId: 'toggle-rest', x: 0, y: 0, width: 100, height: 40 }],
            svg: `<svg viewBox="0 0 100 40"><text x="6" y="22">{{timers.rest.remainingText}}</text></svg>`,
          },
        ],
      },
    },
  },
});

Exécuter les actions depuis l'application

Les widgets natifs peuvent déclencher les mêmes actions à travers leur hotspot/action. L'application peut également les exécuter directement :

await CapgoWidgetKit.performTemplateAction({
  activityId: activity.activityId,
  actionId: 'toggle-rest',
  sourceId: 'app-pause-play-button',
});

Traiter les événements du widget

Les actions émettent des événements afin que l'application puisse traiter les interactions du widget après le lancement ou la reprise :

const { events } = await CapgoWidgetKit.listTemplateEvents({
  activityId: activity.activityId,
  unacknowledgedOnly: true,
});

for (const event of events) {
  console.log('Widget event:', event.eventName, event.state, event.timers);
}

await CapgoWidgetKit.acknowledgeTemplateEvents({
  activityId: activity.activityId,
});

Mettre à jour ou terminer l'activité

await CapgoWidgetKit.updateTemplateActivity({
  activityId: activity.activityId,
  state: {
    title: 'Back Day',
    frame: 'summary',
    restDurationMs: 120000,
  },
});

await CapgoWidgetKit.endTemplateActivity({
  activityId: activity.activityId,
  state: { title: 'Workout complete', frame: 'summary' },
});

Mutations de cadre

Les mutations de cadre écrivent l'identifiant du cadre actif dans l'état. Un layout peut ensuite le lire avec frameIdPath.

Opération	Comportement
set	Définir un identifiant de cadre spécifique. Les chaînes de caractères simples sont traitées comme des identifiants de cadre littéraux ; {{...}} les modèles sont résolus en premier.
next	Passer au cadre suivant frameIds ou les cadres déclarés sur surface.
previous	Passer au cadre précédent.
toggle	Alternent entre les deux premiers cadres disponibles, ou entre le cadre actuel et frameId.

Les identifiants de cadres invalides sont ignorés lorsque la mutation a une liste de cadres sélectionnables connus, afin que l'état reste aligné avec la surface affichée.

Mutations de temporisation

Les mutations de temporisation ciblent un horloge nommée de definition.timers.

Opération	Comportement
start / restart	Commencez à zéro en utilisant la durée actuelle.
pause	Enregistrez le temps écoulé et effacez startedAt.
resume	Résumez uniquement les temporisateurs arrêtés. Les temporisateurs arrêtés restent arrêtés jusqu'à un démarrage explicite ou un redémarrage.
toggle	Arrêtez un chronographe en cours ou réactivez un chronographe suspendu.
reset	Effacez le temps écoulé et revenez à l'état d'arrêt.
stop	Effacez les progrès de l'exécution et marquez le chronographe arrêté.
setDuration	Récalculez l'état après une modification de durée.

Les liaisons de chronographe sont disponibles pour SVG comme {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}} et champs liés.

Option 2 : Session de widget natif intégrale

Use this mode when the widget UI is built in native code. The plugin gives the app and widget a shared session record and a message queue.

const { session } = await CapgoWidgetKit.startWidgetSession({
  widgetId: 'native-session-1',
  kind: 'workout-controls',
  state: { isRunning: true, selectedSetId: 'set-1' },
  metadata: { accent: '#00d69c' },
});

await CapgoWidgetKit.updateWidgetSession({
  widgetId: session.widgetId,
  merge: true,
  state: { isRunning: false },
});

const { sessions } = await CapgoWidgetKit.listWidgetSessions();
console.log('Known widget sessions:', sessions);

Section intitulée “Messages de widget asynchrone”

Messages couvrent le travail qui nécessite une réponse ultérieure, comme un widget demandant à l'application de synchroniser les données.

const { message } = await CapgoWidgetKit.sendWidgetMessage({
  widgetId: session.widgetId,
  direction: 'widgetToApp',
  name: 'syncWorkoutSet',
  payload: { setId: 'set-1' },
  expectsResponse: true,
});

await CapgoWidgetKit.acknowledgeWidgetMessages({
  messageIds: [message.messageId],
});

await CapgoWidgetKit.completeWidgetMessage({
  messageId: message.messageId,
  response: { synced: true },
});

Pour faire fail le job, passez error au lieu de response:

await CapgoWidgetKit.completeWidgetMessage({
  messageId: message.messageId,
  error: 'Network unavailable',
});

completeWidgetMessage est idempotent. Si le message est déjà terminé ou échoué, les appels répétés retournent l'instance de message existante.

Arrêter une session native

await CapgoWidgetKit.stopWidgetSession({
  widgetId: session.widgetId,
  state: { isRunning: false },
});

API Groupes

Groupe	APIs
Capacité	areActivitiesSupported, getPluginVersion
Cycle de vie de l'activité SVG	startTemplateActivity, updateTemplateActivity, endTemplateActivity, getTemplateActivity, listTemplateActivities
Actions et événements SVG	performTemplateAction, listTemplateEvents, acknowledgeTemplateEvents
Sessions de widgets natifs	startWidgetSession, updateWidgetSession, stopWidgetSession, getWidgetSession, listWidgetSessions
Messages de widgets natifs	sendWidgetMessage, listWidgetMessages, acknowledgeWidgetMessages, completeWidgetMessage

Source De Vérité

La référence de type complète se trouve dans le dépôt de plugin à src/definitions.ts.

Continuez de Getting Started

Si vous utilisez Démarrage pour planifier le travail de plugin natif, le connecter avec Utilisation de @capgo/capacitor-kit de widgets pour la capacité native dans l'utilisation de @capgo/capacitor-kit de widgets, Répertoire de plugin Capgo pour le flux de travail du produit dans Répertoire de plugin Capgo, Capacitor Plugins par Capgo pour le détail d'implémentation dans Capacitor Plugins par Capgo, Ajout ou mise à jour de plugins pour le détail d'implémentation dans Ajout ou mise à jour de plugins, et Alternatives de plugins Enterprise Ionic pour le flux de travail du produit dans Alternatives de plugins Enterprise Ionic.