Widget Kit

Utilisation de @capgo/capacitor-kit-de-widget

@capgo/capacitor-widget-kit permet à l'application Capacitor de faire fonctionner les expériences WidgetKit et Live Activity de deux manières :

• Rendre des surfaces de modèle SVG résolu avec le changement de cadre, les zones de clic chaud et les compteurs de pause/lecture.
• Maintenez l'ensemble du widget natif tout en partageant l'état de session JSON et les messages asynchrone 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 ultérieurement.

Les bonnes affaires incluent 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 et reconnaîtrez-les 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 Pleinement Natives

Utilisez des sessions pleinement natives lorsque l'UI du widget est mieux construit directement en Swift, Kotlin ou Java. Capacitor démarre et arrête toujours la session, maintient l'état partagé à jour, et file le travail 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 le travail asynchrone entre le widget et l'application

Les messages peuvent circuler de l'application vers le widget ou du widget vers l'application. Ils restent en attente jusqu'à ce qu'ils soient confirmés 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 faille, complétez 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 de configuration Native

Pour iOS WidgetKit et Live Activities, configurez un groupe d'application sur les cibles de l'application et de l'extension 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-widget-kit/
• Docs : /docs/plugins/widget-kit/

Continuez à partir de l'utilisation de @capgo/capacitor-widget-kit

Si vous utilisez En utilisant @capgo/capacitor-widget-kit pour planifier le travail de plugin natif, connectez-le à @capgo/capacitor-widget-kit pour les détails d'implémentation dans @capgo/capacitor-widget-kit, Démarrage pour les détails d'implémentation dans Démarrage, Répertoire de plugin Capgo pour le flux de travail du produit dans Répertoire de plugin Capgo, et Plugins Capacitor par Capgo pour les détails d'implémentation dans Plugins Capacitor par Capgo, et Ajouter ou mettre à jour des plugins pour les détails d'implémentation dans l'ajout ou la mise à jour des plugins.