Prise en main

Installer

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

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

Utilisez ensuite le prompt suivant :

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 une installation manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à chaque plateforme ci-dessous :

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

Importer

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

Démarrage rapide

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

const result = await CapgoWidgetKit.areActivitiesSupported();
console.log(result);

Exemple : startTemplateActivity

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

const result = await CapgoWidgetKit.startTemplateActivity({
  definition: {
    id: 'id-123',
    layouts: {},
  },
  state: {},
});
console.log(result);

Exemple : startTemplateWidget

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

const result = await CapgoWidgetKit.startTemplateWidget({
  definition: {
    id: 'id-123',
    layouts: {},
  },
  state: {},
});
console.log(result);

Erreurs courantes

• Sync native : exécuter bunx cap sync après les mises à jour du plugin.
• Source de vérité : fiez-vous src/definitions.ts au repo GitHub.

Configuration iOS

Pour les Live Activities et les extensions WidgetKit, configurez d'abord l'application native :

• Utilisez iOS 17+ pour les boutons de Live Activity interactifs dès que possible.
• Ajoutez NSSupportsLiveActivities à l'application Info.plist lors de l'utilisation d'ActivityKit.
• Ajoutez le même App Group à la cible de l'app et à la cible de l'extension du widget.
• Définissez CapgoWidgetKitAppGroup dans les deux Info.plist fichiers sur l'identifiant de l'App Group partagé.

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

Vérifier la prise en charge

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

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

Option 1 : activité SVG Template

Utilisez ce mode lorsque le widget peut afficher un SVG résolu. Le plugin stocke l'état, résout les placeholders, applique les actions de tap, bascule entre les frames SVG et garde l'état du timer 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 des actions depuis l'app

Les widgets natifs peuvent déclencher les mêmes actions via leur configuration hotspot/action. L'app 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

Actions emit events so the app can process widget interactions after launch or resume:

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

Sur iOS, les boutons d'extension de widget peuvent invoquer des helpers LiveActivityIntent inclus (CapgoTemplateActionIntent) qui écrivent dans le même journal d'événements. Cela est distinct des phrases de raccourcis Siri ou de l'application Raccourcis. Voir Siri, Raccourcis et widgets.

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 frame

Les mutations de frame écrivent l'id de la frame active dans l'état. Un layout peut ensuite le lire avec frameIdPath.

Operation	Comportement
set	Définir un id de frame spécifique. Les chaînes simples sont traitées comme des ids de frame littéraux ; {{...}} les templates sont résolus en premier.
next	Passer à la frame suivante depuis frameIds ou les frames déclarées sur surface.
previous	Passer à la frame précédente.
toggle	Bascule entre les deux premières frames disponibles, ou entre la frame actuelle et frameId.

Les IDs de frame invalides sont ignorés lorsque la mutation possède une liste de frames sélectionnables connue, l'état reste donc aligné avec la surface rendue.

Mutations de timer

Les mutations de timer ciblent un timer nommé depuis definition.timers.

Opération	Comportement
start / restart	Repartir de zéro en utilisant la durée actuelle.
pause	Stocker le temps écoulé et effacer startedAt.
resume	Reprendre uniquement les timers en pause. Les timers arrêtés restent arrêtés jusqu'à un démarrage ou un redémarrage explicite.
toggle	Mettez en pause un minuteur en cours ou relancez un minuteur en pause.
reset	Effacer le temps écoulé et revenir à l'état d'inactivité.
stop	Effacer la progression de l'exécution et marquer l'arrêt du minuteur.
setDuration	Recalculer le statut après un changement de durée.

Timer bindings are available to SVG as {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}, et les champs associés.

Option 2 : Session de widget full-native

Utilisez ce mode lorsque l'interface du widget est construite en code natif. Le plugin fournit à 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 widget asynchrones

Les messages couvrent les tâches nécessitant une réponse ultérieure, comme un widget demandant à l'app de synchroniser des 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 é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 a échoué, les appels répétés renvoient le snapshot du message existant.

Arrêter une session native

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

API Groupes

Groupe	API
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 types complète se trouve dans le dépôt du plugin à src/definitions.ts.

Continuer depuis Getting Started

Si vous utilisez Prise en main pour planifier le travail sur les plugins natifs, connectez-l’à Utiliser @capgo/capacitor-widget-kit pour la capacité native dans l'utilisation de @capgo/capacitor-widget-kit, Capgo Répertoire des plugins pour le workflow produit dans Capgo Plugin Directory, Plugins Capacitor par Capgo pour les détails d'implémentation dans Plugins Capacitor par Capgo, Ajouter ou mettre à jour des plugins pour les détails d'implémentation dans Ajout ou mise à jour de plugins, et Alternatives aux plugins Ionic Enterprise pour le workflow produit dans Alternatives aux plugins Ionic Enterprise.