Kit de widgets

En utilisant @capgo/capacitor-widget-kit

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

• Rendre des surfaces de modèles SVG résolus avec le changement de cadre, les zones de clic et les compteurs d'arrêt/démarrage.
• Conservez la widget complètement native tout en partageant l'état de session JSON et les messages asynchrones entre l'application et la widget.

Installer

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

Utiliser les Modèles SVG

Utilisez les modèles SVG lorsque la surface de la widget peut être décrite en SVG. L'application stocke une définition de modèle, le pont natif résout les placeholders et les appuis de la widget peuvent muter l'état ultérieurement.

Les bonnes correspondances incluent les chronomètres 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 de la Widget Dans l'Application

Les actions de la widget sont persistées sous forme d'événements. Lisez et les reconnaîtrez 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 });

Utiliser les Sessions Complètement Natives

Utilisez les sessions complètement natives lorsque l'UI de la 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 la 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 la Widget et l'Application

Les messages peuvent passer de l'application à la widget ou de la 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 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 Native

Pour iOS WidgetKit et Activités en Direct, configurez un Groupe d'Application sur les cibles de l'application et de l'extension de widget, et définissez CapgoWidgetKitAppGroup dans les deux Info.plist dossiers. 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-widget/
• Documentation : /docs/plugins/widget-kit/

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

Si vous utilisez Utilisation de @capgo/capacitor-kit-de-widget/ planifier le travail de plugin natif, le connecter à @capgo/capacitor-kit-de-widgets pour les détails d'implémentation dans @capgo/capacitor-kit-de-widgets, Prise en main pour les détails d'implémentation dans Prise en main, Répertoire des plugins Capgo pour le flux de travail du produit dans Répertoire des plugins Capgo, 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 Ajouter ou mettre à jour des plugins.