Widget Kit

Mit @capgo/capacitor-widget-kit lässt sich eine capgo-App WidgetKit- und Live-Aktivitäts-Erfahrungen in zwei Arten steuern:

@capgo/capacitor-widget-kit lets a Capacitor app drive WidgetKit and Live Activity experiences in two ways:

• Halten Sie das Widget vollständig nativ, während die App und das Widget JSON-Sitzungsstate und asynchrone Nachrichten teilen.
• Installieren

Installieren

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

When zu verwenden SVG-Vorlagen

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

Gute Anwendungen umfassen Trainingszähler, Zustellstatuskarten, Sportergebnisse oder jede kompakte Benutzeroberfläche, 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>`,
          },
        ],
      },
    },
  },
});

Behandeln Sie Widgetaktionen in der App

Widgetaktionen werden als Ereignisse persistiert. Lesen und bestätigen Sie sie, wenn die App wieder aufgerufen wird oder nach einem Hintergrund-Synchronisierungsschritt.

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 zu verwenden Voll-Native Sitzungen

Verwenden Sie voll-native Sitzungen, wenn die Widget-Benutzeroberfläche besser direkt in Swift, Kotlin oder Java erstellt werden kann. Capacitor startet und beendet die Sitzung, hält den gemeinsamen Zustand aktuell und stellt die Arbeit zwischen App und Widget code an die Warteschlange.

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

Warteschlange Asynchrone Arbeit zwischen Widget und App

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

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 der Job fehlschlägt, complete die Nachricht mit einem Fehler:

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

Beenden Sie Sitzungen sauber

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

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

Hinweise zur native Setup

Für iOS WidgetKit und Live Activities, konfigurieren Sie einen App-Gruppen auf der Anwendung und Widget-Erweiterungszieldarstellung 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-Intents verbindet.

Vollständige Referenz

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

Fahren Sie mit dem Lesen von Using @capgo/capacitor-widget-kit fort

Wenn Sie @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kit verwenden Using @capgo/capacitor-widget-kit @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kit Using @capgo/capacitor-widget-kit zur Implementierungsdetail in @capgo/capacitor-widget-kit, Anfänger zur Implementierungsdetail in Anfänger, Capgo Plugin-Verzeichnis zur Produktworkflow in Capgo Plugin-Verzeichnis, Capacitor Plugins von Capgo zur Implementierungsdetail in Capacitor Plugins von Capgo, und Plugins hinzufügen oder aktualisieren zur Implementierungsdetail in Plugins hinzufügen oder aktualisieren.