Widget-Kit

Mit @capgo/capacitor-widget-kit

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

• Rendert SVG-Vorlagenoberflächen mit Frame-Switching, Tastenhotspots und Pause/Spiel-Timern.
• Halten Sie das Widget vollständig nativ, während die App und das Widget JSON-Sitzungsstate und asynche Nachrichten teilen.

Installieren

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

Wann Verwenden Sie 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.

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

Verarbeiten Sie Widget-Aktionen in der App

Widget-Aktionen werden als Ereignisse gespeichert. Lesen und bestätigen Sie sie, wenn die App wieder aufgenommen 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 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 die Arbeit zwischen App und Widget code an.

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

Warten Sie auf asynche 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, beenden Sie 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 Anwendung und Widget-Erweiterungsziele 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 der Verwendung von @capgo/capacitor-widget-kit fort

Wenn Sie @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kit verwenden Wenn Sie @capgo/capacitor-widget-kit verwenden für die Planung von native Plugin-Arbeiten, verbinden Sie es mit @capgo/capacitor-Widget-Kit für die Implementierungsdetails in @capgo/capacitor-Widget-Kit Anleitung zum Starten für die Implementierungsdetails in Anleitung zum Starten Capgo Plugin-Verzeichnis für den Produktworkflow in 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.