Accueil

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

Ensuite, utilisez 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 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 au cible de l'application et à la cible de l'extension de widget.
• Définir CapgoWidgetKitAppGroup dans les deux Info.plist fichiers au 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 SVG d'activité

Utilisez ce mode lorsque le widget peut rendre 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 des actions depuis l'application

Les widgets natifs peuvent déclencher les mêmes actions grâce à leur hotspot/branchement d'action. L'application peut 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'ID du cadre actif dans l'état. Un layout peut ensuite le lire avec frameIdPath.

Opération	Comportement
set	Définir un ID de cadre spécifique. Les chaînes de caractères simples sont traitées comme des IDs de cadre littéraux ; {{...}} 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 au cadre précédent.
toggle	Alternner entre les deux premiers cadres disponibles, ou entre le cadre actuel et frameId.

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

Mutations de temporisateur

Les mutations de temporisateur s'attaquent à un temporisateur nommé 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 temporisateur en cours ou résumez un temporisateur arrêté.
reset	Effacez le temps écoulé et revenez à l'état inactif.
stop	Effacez les progrès de temps d'exécution et marquez le temporisateur arrêté.
setDuration	Récalculez l'état après une modification de durée.

Les liens de temporisation sont disponibles pour SVG ainsi que {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}et les champs connexes.

Option 2 : Session de widget native complète

Utilisez ce mode lorsque l'interface utilisateur du widget est construite en code. Le plugin donne au widget et à l'application 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 le travail qui nécessite une réponse ultérieure, comme un widget qui demande à 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 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

APIs	Capacité
Cycle de vie de l'activité SVG	areActivitiesSupported, getPluginVersion
Actions et événements SVG	startTemplateActivity, updateTemplateActivity, endTemplateActivity, getTemplateActivity, listTemplateActivities
Copier dans le presse-papier	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 complète du type 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’avec Utilisez @capgo/capacitor-widget-kit pour la capacité native dans Utilisez @capgo/capacitor-widget-kit, Répertoire des plugins Capgo pour le flux de travail du produit dans le Capgo Répertoire des plugins Capacitor Plugins par Capgo pour le détail d'implémentation dans les Capacitor Plugins 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 les Alternatives de Plugins d'Entreprise Ionic.