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:

• Bewahrt die Widgetoberfläche vollständig als native Oberfläche, während die App und das Widget JSON-Sitzungsstate und asynchrone Nachrichten austauschen.
• Installation

SVG-Vorlagen verwenden, 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.

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

Installieren

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.

Installieren ist nicht erforderlich, 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. Wenn die Widgetoberfläche als SVG beschrieben werden kann, ist es eine gute Wahl, wenn die App und das Widget JSON-Sitzungsstate und asynchrone Nachrichten austauschen können. Beispiele für gute Anwendungen sind Workout-Timer, Lieferstatuskarten, Sportergebnisse oder jede kompakte UI, bei der zwischen benannten Frames gewechselt werden kann.

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-Handlungen im App bearbeiten

Widget-Handlungen werden als Ereignisse gespeichert. Lesen und bestätigen Sie sie, wenn die App wieder aufgerufen 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 Voll-Native Sitzungen verwenden

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

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

Arbeiten zwischen Widget und App in der Warteschleife einstellen

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 Warteschleife.

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

Sitzungen sauber beenden

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

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

Hinweise zur nativen Einrichtung

Für iOS WidgetKit und Live Activities konfigurieren Sie einen App-Gruppen auf der App- und Widget-Erweiterungszieldarstellungen und setzen Sie CapgoWidgetKitAppGroup in beiden Info.plist Dateien. Interaktive Schaltflächen erfordern eine Widget-Erweiterung, die den vom Plugin bereitgestellten nativen Bridge und die Aktion-Intents verbindet.

Vollständige Referenz

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