WidgetKit Plugin Capacitor

Utiliser @capgo/capacitor-widget-kit

@capgo/capacitor-widget-kit permet à une app Capacitor de piloter des expériences WidgetKit et Live Activity de deux manières :

• Affichez des surfaces de templates SVG résolues avec changement de frames, hotspots au tap et minuteurs lecture/pause.
• Gardez le widget entièrement natif pendant que l'app et le widget partagent l'état de session JSON et des messages asynchrones.

Installer

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

Quand utiliser les templates SVG

Utilisez des templates SVG quand la surface du widget peut être décrite en SVG. L'app stocke une définition de template, le bridge natif résout les placeholders, et les clics sur le widget peuvent ensuite modifier l'état.

Cas d'usage idéaux : minuteurs d'entraînement, cartes de statut de livraison, scores sportifs, ou toute UI compacte où basculer entre des frames nommées suffit.

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

const { activity } = await CapgoWidgetKit.startTemplateActivity({
  activityId: 'session-1',
  state: {
    title: 'Chest Day',
    frame: 'summary',
    restDurationMs: 90000,
  },
  definition: {
    id: 'workout-card',
    timers: [{ id: 'rest', durationPath: 'state.restDurationMs' }],
    actions: [
      {
        id: 'next-frame',
        frameMutations: [{ op: 'next', path: 'frame', surface: 'lockScreen' }],
      },
      {
        id: 'toggle-rest',
        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>`,
          },
        ],
      },
    },
  },
});

Gérer les actions des widgets dans l'app

Les actions de widget sont persistées sous forme d'événements. Lisez-les et acquittez-les lors de la reprise de l'app ou après une étape de synchronisation en arrière-plan.

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

for (const event of events) {
  console.log(event.actionId, event.state, event.timers);
}

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

Quand utiliser les sessions full-native

Utilisez des sessions full-native lorsque l'UI du widget gagne à être construite directement en Swift, Kotlin ou Java. Capacitor démarre et arrête toujours la session, maintient l'état partagé à jour et met en file d'attente le travail entre l'app et le widget code.

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

Mettre en file d'attente l'async entre widget et app

Les messages peuvent circuler de l'app vers le widget ou inversement. Ils restent en attente jusqu'à leur confirmation et leur achèvement.

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

Si la tâche échoue, terminez le message avec une erreur :

await CapgoWidgetKit.completeWidgetMessage({
  messageId: message.messageId,
  error: 'Sync failed',
});

Arrêter les sessions proprement

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

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

Notes sur la configuration native

Pour iOS WidgetKit et Live Activities, configurez un App Group sur les cibles de l'app et de l'extension du widget, puis définissez CapgoWidgetKitAppGroup dans les deux Info.plist fichiers. Les boutons interactifs nécessitent une extension de widget qui relie le bridge natif fourni par le plugin et l'action intent.

Référence complète

• GitHub : https://github.com/Cap-go/capacitor-widget-kit/
• Docs : /docs/plugins/widget-kit/

Continuer depuis Utiliser @capgo/capacitor-widget-kit

Si vous utilisez Utiliser @capgo/capacitor-widget-kit pour planifier le travail sur les plugins natifs, connectez-l’à @capgo/capacitor-widget-kit pour les détails d'implémentation dans @capgo/capacitor-widget-kit, Prise en main pour les détails d'implémentation dans Getting Started 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 les plugins Capacitor par Capgo, et Ajouter ou mettre à jour des plugins pour les détails d'implémentation dans Adding or Updating Plugins.