Kit de widgets Capacitor kit de plugins

En utilisant @capgo/capacitor-widget-kit

@capgo/capacitor-widget-kit Permet à une application Capacitor de piloter les expériences de WidgetKit et d'activité en direct de deux manières.

• Afficher des modèles SVG résolus avec changement de cadre, zones de clic et temporisations pause/lecture.
• Conservant le widget entièrement natif tandis que l'application et le widget partagent un état de session JSON et des messages asynchrones.

Installer

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

Quand utiliser des modèles SVG

Utilisez des 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 placeholders et les appuis sur le 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 reconnaissiez-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 les Sessions Pleinement Natives

Use full-native sessions when the widget UI is better built directly in Swift, Kotlin, or Java. Capacitor still starts and stops the session, keeps shared state current, and queues work between app and 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 },
});

Queue Async Work Between Widget And App

Les messages peuvent circuler entre l'application et le widget ou vice versa. Ils restent en attente jusqu'à être confirmés et traité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 faille, complétez le message avec une erreur :

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

Remarques de configuration native.

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

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

Remarques de configuration native

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

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

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