Widget Kit

Verwendung von @capgo/capacitor-widget-kit

@capgo/capacitor-widget-kit Lassen Sie ein Capacitor-App WidgetKit- und Live-Aktivitäts-Erfahrungen in zwei Arten steuern:

• Rendern Sie SVG-Vorlagenoberflächen mit Frame-Wechsel, Tastenhotspots und Pause/Spiel-Timern.
• Halten Sie das 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 Verwenden Sie SVG-Vorlagen?

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

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

Behandeln Sie Widget-Aktionen im App

Widget-Aktionen werden als Ereignisse persistiert. Lesen und bestätigen Sie sie, wenn das 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 });

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 stoppt die Sitzung noch immer, hält den gemeinsamen Zustand aktuell und stellt 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 asynchrone Arbeit zwischen Widget und App

Nachrichten können von der App auf das Widget oder umgekehrt fließen. Sie bleiben bis bestätigt und abgeschlossen, unvollständig.

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, vervollständige die Nachricht mit einem Fehler:

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

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-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/

Weitermachen von @capgo/capacitor-widget-kit

Wenn Sie verwenden Mit @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, Einführung für die Implementierungsdetails in Einführung, 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 Hinzufügen oder Aktualisieren von Plugins für die Implementierungsdetails in Plugins hinzufügen oder aktualisieren.