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 To Use SVG-Vorlagen

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

Einige gute Anwendungen sind 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>`,
          },
        ],
      },
    },
  },
});

Verarbeiten Sie Widgetaktionen in der App

Widgetaktionen werden als Ereignisse gespeichert. 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 To Use Voll-Native Sitzungen

Verwenden Sie voll-native Sitzungen, wenn die Widget-UI besser direkt in Swift, Kotlin oder Java erstellt werden kann. Capacitor startet und beendet die Sitzung, hält den gemeinsamen Zustand aktuell und stellt 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 },
});

Warteschleifen Sie 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 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 Arbeit 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 den Anwendungs- 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-Intents verbindet.

Vollständige Referenz

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

Fortsetzen Sie von Using @capgo/capacitor-widget-kit

Wenn Sie Using @capgo/capacitor-widget-kit zum Planen von native Plugin-Arbeiten verwenden, verbinden Sie es mit @capgo/capacitor-widget-kit für die Implementierungsdetails in @capgo/capacitor-widget-kit Einstieg für die Implementierungsdetails in Einstieg Capgo Plugin-Verzeichnis für den Produktworkflow in Capgo Plugin-Verzeichnis Capacitor Plugins von Capgo für die Implementierungsdetails in Capacitor Plugins von Capgo Plugins hinzufügen oder aktualisieren für die Implementierungsdetails in Plugins hinzufügen oder aktualisieren