Getting Started

Installer

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.
• Ajouter 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éfinir 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érifier le support

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

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

Option 1 : Modèle d'activité SVG

Utilisez ce mode lorsque le widget peut afficher l'SVG résolu. Le plugin stocke l'état, résout les placeholders, 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',
});

Processer 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'ID du cadre actif dans l'état. Un layout peut ensuite le lire avec frameIdPath.

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

Les identifiants de frame non valides sont ignorés lorsque la mutation a une liste de frames sélectionnables connue, afin que l'état reste aligné avec la surface affichée.

Mutations de temporisation

Les mutations de temporisation visent 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 temporisations arrêtées. Les temporisations arrêtées restent arrêtées jusqu'à un démarrage explicite ou un redémarrage.
toggle	Interrompez une temporisation en cours ou résumez une temporisation arrêtée.
reset	Effacez le temps écoulé et revenez à l'état d'inactivité.
stop	Effacez les progrès de l'exécution et marquez la temporisation arrêtée.
setDuration	Récalculez l'état après un changement de durée.

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

Option 2 : Session de widget natif complète

Utilisez ce mode lorsque l'interface utilisateur du widget est construite en native code. Le plugin donne à l'application et au widget un enregistrement de session partagé et une file d'attente de messages.

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);

Messages de widgets Async

Les 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 échouer la tâche, 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'échantillon de message existant.

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 sur src/definitions.ts.

Continuez de l'interface d'accueil

Si vous utilisez Interface d'accueil pour planifier le travail de plugin natif, connectez-le avec En utilisant @capgo/capacitor-kit de widgets pour la capacité native dans En utilisant @capgo/capacitor-kit de widgets, Répertoire de plugin Capgo pour le flux de travail du produit dans Répertoire de plugin Capgo, Plugins Capacitor par Capgo pour le détail d'implémentation dans Plugins Capacitor par Capgo, Ajouter ou mettre à jour des plugins pour les détails d'implémentation dans l'ajout ou la mise à jour de plugins, et Alternatives de plugins d'entreprise Ionic pour le flux de travail du produit dans Alternatives de plugins d'entreprise Ionic.