Prise en main

Installer

Vous pouvez utiliser notre configuration assistée par l'IA pour installer le plugin. Ajoutez les Capgo compétences à votre outil IA à l'aide de la commande suivante :

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

Utilisez ensuite la prompt 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 des boutons d'activité interactifs lorsqu'il est possible.
• Ajoutez NSSupportsLiveActivities à l'application Info.plist ajoutez-l’à l'application
• Ajoutez le même groupe d'application au cible de l'application et au cible de l'extension de widget.
• Set CapgoWidgetKitAppGroup Configurez Info.plist fichiers vers l'identifiant de groupe d'applications partagé.

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

copiez dans le presse-papier

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, 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 de câblage. 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

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

Mettre à jour ou arrêter 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	Set a specific frame id. Plain strings are treated as literal frame ids; {{...}} les modèles sont résolus en premier.
next	Passer au cadre suivant à partir de frameIds ou les cadres déclarés sur surface.
previous	Passer à la frame précédente.
toggle	Alternner entre les deux premières frames disponibles, ou entre la frame actuelle et frameId.

Les identifiants de frames invalides 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 ciblent un horloge nommée definition.timers.

Opération	Comportement
start / restart	Démarrer à zéro en utilisant la durée actuelle.
pause	Enregistrer le temps écoulé et effacer startedAt.
resume	Resume only paused timers. Stopped timers stay stopped until an explicit start or restart.
toggle	Arrêter un chronomètre en cours ou reprendre un chronomètre arrêté.
reset	Clear elapsed time and return to idle.
stop	Effacer les progrès de l'exécution et marquer le chronomètre arrêté.
setDuration	Recalculer l'état après un changement de durée.

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

Option 2 : Session de widget native complète

Utilisez ce mode lorsque l'interface utilisateur du widget est construite en 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 widget asynchrone

Les messages couvrent les tâches nécessitant 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 failir 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 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 du plugin à src/definitions.ts.

Continuez de Getting Started

Si vous utilisez Getting Started pour planifier le travail de plugin natif, connectez-l’à En utilisant @capgo/capacitor-kit de widget pour la capacité native dans En utilisant @capgo/capacitor-kit de widget __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 les plugins pour le détail d'implémentation dans Ajouter ou Mettre à jour les plugins, et Alternatives de plugins d'entreprise Ionic pour le flux de travail du produit dans Alternatives de plugins d'entreprise Ionic.