WidgetKit Capacitor Plugin

@capgo/capacitor-widget-kit verwenden

@capgo/capacitor-widget-kit ermöglicht es einer Capacitor-App, WidgetKit- und Live-Activity-Erlebnisse auf zwei Arten zu steuern:

• Rendere aufgelöste SVG-Template-Oberflächen mit Frame-Wechseln, Tap-Hotspots und Pause/Play-Timern.
• Behalte das Widget vollständig nativ, während App und Widget JSON-Session-State und asynchrone Nachrichten teilen.

Installieren

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

Wann SVG-Templates nutzen

Nutze SVG-Templates, wenn die Widget-Oberfläche als SVG beschrieben werden kann. Die App speichert eine Template-Definition, die native Bridge löst Platzhalter auf, und Widget-Taps können den State später ändern.

Ideal geeignet sind Workout-Timer, Lieferstatus-Karten, Sportergebnisse oder jede kompakte UI, bei der das Wechseln zwischen benannten Frames ausreicht.

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>`,
          },
        ],
      },
    },
  },
});

Widget-Aktionen in der App verarbeiten

Widget-Aktionen werden als Events gespeichert. Lies und bestätige sie, wenn die App wieder startet oder nach einem Background-Sync.

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 });

Wann Full-Native Sessions nutzen

Nutze Full-Native-Sessions, wenn das Widget-UI direkt in Swift, Kotlin oder Java besser umgesetzt ist. Capacitor startet und stoppt die Session weiterhin, hält den Shared State aktuell und queued die Arbeit zwischen App und 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 },
});

Async-Work zwischen Widget und App queuen

Nachrichten können von der App zum Widget oder vom Widget zur App fließen. Sie bleiben pending, bis sie bestätigt und abgeschlossen sind.

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 },
});

Falls der Job fehlschlägt, schließe die Nachricht mit einem Fehler ab:

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

Sessions sauber beenden

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

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

Hinweise zum Native Setup

Konfiguriere für iOS WidgetKit und Live Activities eine App Group für die App- und Widget-Extension-Targets und setze CapgoWidgetKitAppGroup in beiden Info.plist Dateien. Interaktive Buttons benötigen eine Widget-Extension, die die vom Plugin bereitgestellte Native Bridge und den Action Intent verbindet.

Vollständige Referenz

• GitHub: https://github.com/Cap-go/capacitor-widget-kit/
• Docs: /docs/plugins/widget-kit/

Weiter mit der Nutzung von @capgo/capacitor-widget-kit

Wenn du es nutzt @capgo/capacitor-widget-kit verwenden Um die Arbeit an nativen Plugins zu planen, verbinde sie mit @capgo/capacitor-widget-kit für Details zur Implementierung in @capgo/capacitor-widget-kit, Erste Schritte für die Implementierungsdetails in Erste Schritte, Capgo Plugin-Verzeichnis für den Produkt-Workflow im Capgo Plugin-Verzeichnis, Capacitor Plugins von Capgo für die Implementierungsdetails in Capacitor Plugins von Capgo, und Plugins hinzufügen oder aktualisieren für die Implementierungsdetails in Plugins hinzufügen oder aktualisieren.