En utilisant @capgo/capacitor-widget-kit

@capgo/capacitor-widget-kit cela permet à une application Capacitor de faire fonctionner les expériences de WidgetKit et d'Activité en direct de deux manières :

Rendre les surfaces de modèle SVG résolu avec le changement de cadre, les zones de clic et les compteurs d'arrêt/lecture.
Maintenir le widget entièrement natif tout en partageant l'état de session JSON et les messages asynchrones entre l'application et le widget.

Installer

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

Quand Utiliser les Modèles SVG

Utilisez les modèles SVG lorsque la surface du widget peut être décrite en SVG. L'application stocke une définition de modèle, le pont natif résout les marqueurs, et les clics du widget peuvent muter l'état plus tard.

Les bonnes affaires comprennent les compteurs d'entraînement, les cartes d'état de livraison, les scores de sports ou tout UI compact où le passage entre les cadres nommés est suffisant.

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 du widget dans l'application

Les actions du widget sont persistées sous forme d'événements. Lisez-les et les acceptez lorsque l'application reprend ou après une étape de synchronisation de fond.

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 des sessions natives complètes

Utilisez des sessions natives complètes lorsque l'interface utilisateur du widget est mieux construite directement en Swift, Kotlin ou Java. Capacitor démarre et arrête toujours la session, maintient l'état partagé à jour et file les tâches entre l'application 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 },
});

Filez les tâches asynchrones entre le widget et l'application

Les messages peuvent passer de l'application au widget ou du widget à l'application. Ils restent en attente jusqu'à ce qu'ils soient reconnus et terminés.

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êtez 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 de configuration native

Pour les widgets WidgetKit et les activités en direct sur iOS, configurez un groupe d'application sur les cibles de l'extension de l'application et du widget et définissez CapgoWidgetKitAppGroup dans les deux Info.plist fichiers. Les boutons interactifs nécessitent une extension de widget qui relie le pont natif fourni par le plugin et l'intention d'action.

Référence complète

GitHub: https://github.com/Cap-go/capacitor-kit-de-widgets/
Documentation : /docs/plugins/widget-kit/

Kit de widgets

Tutoriel sur le Kit de Widget