Widget Kit Capacitor Plugin

Mit @capgo/capacitor-widget-kit

@capgo/capacitor-widget-kit ermöglicht es einem Capacitor-App, WidgetKit- und Live-Aktivitäts-Erfahrungen auf zwei Arten zu steuern:

• Rendere die gelöste SVG-Vorlage auf Oberflächen mit Frame-Wechsel, Touch-Hotspots und Pause/Spiel-Zählern.
• Hält die Widget vollständig nativ, während das App und Widget JSON-Sitzungsstate und asynchrone Nachrichten teilen.

Installieren

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

Wann man SVG-Vorlagen verwenden soll.

Verwenden Sie SVG-Vorlagen, wenn die Widgetoberfläche als SVG beschrieben werden kann. Die App speichert eine Vorlagendefinition, die native Brücke löst Platzhalter auf und Widget-Tasten können den Zustand später ändern.

Gute Anwendungen sind z.B. Workout-Timer, Lieferstatuskarten, 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>`,
          },
        ],
      },
    },
  },
});

Widgetaktionen im App-Code verwalten

Widgetaktionen werden als Ereignisse gespeichert. Lesen und bestätigen Sie sie, wenn die App neu gestartet wird oder nach einem Hintergrund-Synchronisierungs-Schritt.

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 verwenden Sie Vollständig-Native-Sitzungen

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

Nachrichten können von der App zum Widget oder vom Widget zur App fließen. Sie bleiben bis zur Bestätigung und Abschluss ausstehend.

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

Wenn die Aufgabe fehlschlägt, füllen Sie die Nachricht mit einem Fehler aus:

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

Hinweise zur native Setup

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

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

Einrichtungshinweise für native Apps

Für iOS WidgetKit und Live Activities, konfigurieren Sie einen App-Gruppen auf den App- und Widget-Erweiterungszieldarstellungen und setzen Sie CapgoWidgetKitAppGroup in beiden Info.plist Dateien. Interaktive Schaltflächen erfordern eine Widget-Erweiterung, die die vom Plugin bereitgestellte native Brücke und die Aktion-Intention verbindet.

Vollständige Referenz

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

Weitermachen von Using @capgo/capacitor-widget-kit

Wenn Sie @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kit Verwendung von @capgo/capacitor-Widget-Kit um native Plugin-Arbeit zu planen, verbinden Sie es mit @capgo/capacitor-Widget-Kit für die Implementierungsdetails in @capgo/capacitor-Widget-Kit, Zur Einführung zur Implementierungsdetail in Zur Einführung Capgo Plugin-Verzeichnis zur Produktworkflow in Capgo Plugin-Verzeichnis Capacitor Plugins von Capgo zur Implementierungsdetail in Capacitor Plugins von Capgo, und Hinzufügen oder Aktualisieren von Plugins zur Implementierungsdetail in Hinzufügen oder Aktualisieren von Plugins.