Erste Schritte

Installieren

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:

bunx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Nutze dann diesen Prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-widget-kit` plugin in my project.

Wenn du ein manuelles Setup bevorzugst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

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

Importieren

import { CapgoWidgetKit } from '@capgo/capacitor-widget-kit';

Quickstart

import { CapgoWidgetKit } from '@capgo/capacitor-widget-kit';

const result = await CapgoWidgetKit.areActivitiesSupported();
console.log(result);

Beispiel: startTemplateActivity

import { CapgoWidgetKit } from '@capgo/capacitor-widget-kit';

const result = await CapgoWidgetKit.startTemplateActivity({
  definition: {
    id: 'id-123',
    layouts: {},
  },
  state: {},
});
console.log(result);

Beispiel: startTemplateWidget

import { CapgoWidgetKit } from '@capgo/capacitor-widget-kit';

const result = await CapgoWidgetKit.startTemplateWidget({
  definition: {
    id: 'id-123',
    layouts: {},
  },
  state: {},
});
console.log(result);

Häufige Stolperfallen

• Nativer Sync: ausführen bunx cap sync nach Plugin-Upgrades.
• Single Source of Truth: Vertrauen src/definitions.ts im GitHub Repo.

iOS-Setup

Konfiguriere zuerst die native App für Live Activities und WidgetKit-Extensions:

• Nutze nach Möglichkeit iOS 17+, um interaktive Live Activity-Buttons zu verwenden.
• Füge NSSupportsLiveActivities zur App Info.plist bei der Verwendung von ActivityKit.
• Füge derselben App Group sowohl das App-Target als auch das Widget-Extension-Target hinzu.
• Setzen Sie CapgoWidgetKitAppGroup in beiden Info.plist Dateien zur gemeinsamen App Group Identifier.

<key>CapgoWidgetKitAppGroup</key>
<string>group.app.capgo.widgetkit.exampleapp.widgetkit</string>

Support prüfen

const { supported, reason } = await CapgoWidgetKit.areActivitiesSupported();

if (!supported) {
  console.log('WidgetKit bridge unavailable:', reason);
}

Option 1: SVG-Template-Activity

Nutze diesen Modus, wenn das Widget aufgelöste SVGs rendern kann. Das Plugin speichert den State, löst Platzhalter auf, führt Tap-Actions aus, wechselt SVG-Frames und hält den Timer-State konsistent.

const { activity } = await CapgoWidgetKit.startTemplateActivity({
  activityId: 'workout-session-1',
  openUrl: 'myapp://workout/session-1',
  state: {
    title: 'Chest Day',
    frame: 'summary',
    restDurationMs: 90000,
  },
  definition: {
    id: 'workout-card',
    timers: [
      {
        id: 'rest',
        durationPath: 'state.restDurationMs',
      },
    ],
    actions: [
      {
        id: 'next-frame',
        eventName: 'widget.frame.changed',
        frameMutations: [
          {
            op: 'next',
            path: 'frame',
            surface: 'lockScreen',
          },
        ],
      },
      {
        id: 'toggle-rest',
        eventName: 'widget.timer.toggled',
        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>`,
          },
        ],
      },
    },
  },
});

Aktionen aus der App ausführen

Native Widgets können über ihre Hotspot/Action-Verknüpfung dieselben Aktionen auslösen. Die App kann diese auch direkt ausführen:

await CapgoWidgetKit.performTemplateAction({
  activityId: activity.activityId,
  actionId: 'toggle-rest',
  sourceId: 'app-pause-play-button',
});

Widget-Events verarbeiten

Aktionen emittieren Events, sodass die App Widget-Interaktionen nach dem Start oder dem Resume verarbeiten kann:

const { events } = await CapgoWidgetKit.listTemplateEvents({
  activityId: activity.activityId,
  unacknowledgedOnly: true,
});

for (const event of events) {
  console.log('Widget event:', event.eventName, event.state, event.timers);
}

await CapgoWidgetKit.acknowledgeTemplateEvents({
  activityId: activity.activityId,
});

Unter iOS können Widget-Extension-Buttons gebündelte LiveActivityIntent Helfer (CapgoTemplateActionIntent) aufrufen, die in dasselbe Event-Log schreiben. Dies ist unabhängig von Siri-Kurzbefehlen oder der Shortcuts App. Siehe Siri, Shortcuts und Widgets.

Update oder Activity beenden

await CapgoWidgetKit.updateTemplateActivity({
  activityId: activity.activityId,
  state: {
    title: 'Back Day',
    frame: 'summary',
    restDurationMs: 120000,
  },
});

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

Frame-Mutationen

Frame-Mutationen schreiben die aktive Frame-ID in den State. Ein Layout kann diese dann mit lesen: frameIdPath.

Operation	Verhalten
set	Eine spezifische Frame-ID setzen. Plain Strings werden als literale Frame-IDs behandelt; {{...}} Templates werden zuerst aufgelöst.
next	Zum nächsten Frame wechseln von frameIds oder den auf ... deklarierten Frames surface.
previous	Zum vorherigen Frame wechseln.
toggle	Wechselt zwischen den ersten zwei verfügbaren Frames oder zwischen dem aktuellen Frame und frameId.

Ungültige Frame-IDs werden ignoriert, wenn die Mutation eine bekannte Liste auswählbarer Frames hat, damit der State mit der gerenderten Oberfläche synchron bleibt.

Timer-Mutationen

Timer-Mutationen zielen auf einen benannten Timer von definition.timers.

Operation	Verhalten
start / restart	Mit der aktuellen Dauer bei Null starten.
pause	Vergangene Zeit speichern und startedAt.
resume	Nur pausierte Timer fortsetzen. Gestoppte Timer bleiben gestoppt, bis sie explizit gestartet oder neu gestartet werden.
toggle	Pausiere einen laufenden Timer oder setze einen pausierten Timer fort.
reset	Clear elapsed time and return to idle.
stop	Laufzeitfortschritt löschen und den Timer als gestoppt markieren.
setDuration	Status nach einer Änderung der Dauer neu berechnen.

Timer-Bindings stehen in SVG als zur Verfügung: {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}, sowie zugehörige Felder.

Option 2: Vollständige Native Widget-Session

Nutze diesen Modus, wenn das Widget-UI in nativem code gebaut wird. Das Plugin stellt der App und dem Widget eine gemeinsame Session-Record und eine Message Queue bereit.

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

const { sessions } = await CapgoWidgetKit.listWidgetSessions();
console.log('Known widget sessions:', sessions);

Asynchrone Widget-Nachrichten

Messages cover work that needs a later response, such as a widget asking the app to sync data.

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

Um den Job fehlschlagen zu lassen, übergeben Sie error anstatt response:

await CapgoWidgetKit.completeWidgetMessage({
  messageId: message.messageId,
  error: 'Network unavailable',
});

completeWidgetMessage ist idempotent. Wenn die Nachricht bereits abgeschlossen oder fehlgeschlagen ist, liefern wiederholte Aufrufe den vorhandenen Message-Snapshot zurück.

Native Session stoppen

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

API Gruppen

Gruppe	APIs
Funktion	areActivitiesSupported, getPluginVersion
SVG-Lebenszyklus der Aktivität	startTemplateActivity, updateTemplateActivity, endTemplateActivity, getTemplateActivity, listTemplateActivities
SVG-Aktionen und Events	performTemplateAction, listTemplateEvents, acknowledgeTemplateEvents
Native Widget-Sessions	startWidgetSession, updateWidgetSession, stopWidgetSession, getWidgetSession, listWidgetSessions
Native Widget-Messages	sendWidgetMessage, listWidgetMessages, acknowledgeWidgetMessages, completeWidgetMessage

Source of Truth

Die vollständige Typ-Referenz findest du im Plugin-Repository unter src/definitions.ts.

Weiter geht's nach Getting Started

Wenn du es nutzt Erste Schritte Um die Arbeit an nativen Plugins zu planen, verbinde sie mit @capgo/capacitor-widget-kit verwenden für die native Funktion in „@capgo/capacitor-widget-kit verwenden“, Capgo Plugin-Verzeichnis für den Produkt-Workflow im Capgo Plugin-Verzeichnis, Capacitor Plugins von Capgo für das Implementierungsdetail in Capacitor Plugins von Capgo, Plugins hinzufügen oder aktualisieren für das Implementierungsdetail beim Hinzufügen oder Aktualisieren von Plugins, und Ionic Enterprise Plugin-Alternativen für den Produkt-Workflow bei den Ionic Enterprise Plugin-Alternativen.