Kit de widgets

En utilisant @capgo/capacitor-widget-kit

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

• Rendre les surfaces de modèle SVG résolu avec le changement de cadre, les hotspots de tap et les compteurs de pause/jeu.
• Conservez le widget entièrement natif tout en partageant l'état de session JSON et les messages asynchrones entre l'application et le widget.

Installez

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

When 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 appuis de widget peuvent muter l'état ultérieurement.

Les bonnes correspondances incluent les chronomètres d'entraînement, les cartes de statut 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 });

When Utiliser les Sessions Complètes-Native

Utilisez les sessions complètes-natives lorsque l'UI du widget est mieux construit directement en Swift, Kotlin ou Java. Capacitor démarre et arrête toujours la session, garde l'état partagé actuel, 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 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 l'opération échoue, complétez le message avec une erreur :

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

Arrêtez les Sessions de Manière Propre

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

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

Notes de Configuration du Développement Native

Configurez un groupe d'application pour iOS WidgetKit et les activités en direct en configurant un groupe d'application sur les cibles de l'application et de l'extension de widget et en définissant CapgoWidgetKitAppGroup à la fois Info.plist dans les 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/
• Documentation : /docs/plugins/widget-kit/

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

Si vous utilisez L'utilisation de @capgo/capacitor-widget-kit pour planifier le travail de plugin natif, connectez-le avec @capgo/capacitor-widget-kit pour les détails d'implémentation dans @capgo/capacitor-kit de widgets Démarrage pour les détails d'implémentation dans Démarrage Capgo Répertoire des plugins pour le flux de travail du produit dans Capgo Répertoire des plugins Capacitor Plugins par Capgo pour les détails d'implémentation dans Capacitor Plugins par Capgo Ajouter ou Mettre à Jour les Plugins pour les détails d'implémentation dans Ajouter ou Mettre à Jour les Plugins