Getting Started

Installieren

Sie können unsere AI-gestützte Einrichtung verwenden, um das Plugin zu installieren. Fügen Sie die Capgo Fähigkeiten Ihrem AI-Tool mit der folgenden Befehl hinzu:

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

Verwenden Sie dann den folgenden Prompt:

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

Wenn Sie eine manuelle Einrichtung bevorzugen, installieren Sie das Plugin, indem Sie die folgenden Befehle ausführen und die darunter angegebenen Plattform-spezifischen Anweisungen befolgen.

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

Importieren

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

iOS-Einrichtung

Für Live-Aktivitäten und WidgetKit-Erweiterungen konfigurieren Sie das native App zuerst:

• Verwenden Sie iOS 17+ für interaktive Live-Aktivitäts-Buttons, wenn möglich.
• Hinzufügen NSSupportsLiveActivities zum App Info.plist Wenn Sie ActivityKit verwenden.
• Fügen Sie dem App-Target und dem Ziel für die Widget-Erweiterung denselben App-Gruppen-Name zu.
• Set CapgoWidgetKitAppGroup in beiden Info.plist Dateien zum gemeinsamen App-Gruppen-Bezeichner übertragen.

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

Überprüfen Sie die Unterstützung

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

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

Option 1: SVG-Vorlagenaktivität

Verwenden Sie diesen Modus, wenn das Widget die aufgelöste SVG rendern kann. Der Plugin speichert den Zustand, löst Platzhalter auf, anwendet Tastenaktionen, wechselt SVG-Frames und hält den Timerzustand 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 von der App aus ausführen

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

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

Widget-Events verarbeiten

Aktionen senden Ereignisse, damit die App nach dem Start oder Wiederaufnahme die Widget-Interaktionen 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,
});

Die Aktivität aktualisieren oder 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 den aktiven Frame-Id in den Zustand. Ein Layout kann ihn dann mit frameIdPath.

Operation	Verhalten
set	Setzen Sie eine spezifische Frame-ID. Normale Zeichenketten werden als wörtliche Frame-IDs behandelt; {{...}} Vorlagen werden zuerst aufgelöst.
next	Zum nächsten Frame wechseln von frameIds oder den auf der Seite deklarierten Frames surface.
previous	Zum vorherigen Frame wechseln.
toggle	Zwischen den ersten beiden verfügbaren Frames, oder zwischen dem aktuellen Frame und frameId.

Ignorierte Frame-IDs werden bei einer bekannten Liste auswählbarer Frames in der Mutation ignoriert, sodass sich der Zustand mit der renderierten Oberfläche synchronisiert.

Timer-Mutationen

Timer-Mutationen richten sich an eine benannte Timer von definition.timers.

Aktion	Verhalten
start / restart	Starten Sie mit der aktuellen Dauer von vorne an.
pause	Zeit vermerken und löschen startedAt.
resume	Nur unterbrochene Timer fortsetzen. Gesteuerte Timer bleiben bis zu einem expliziten Start oder Neustart gestoppt.
toggle	Pause a running timer or resume a paused timer.
reset	Verlauf gelöscht und in den Idle-Modus zurückkehren.
stop	Fortschritt gelöscht und Timer als gestoppt markieren.
setDuration	Status nach einer Daueränderung neu berechnen.

Timer-Bindungen sind für SVG als {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}und zugehörige Felder verfügbar.

Option 2: Vollständige Widget-Sitzung

Wählen Sie diese Modus, wenn die Widget-UI in native code. gebaut wird. Der Plugin gibt dem App und Widget einen gemeinsamen Sitzungsrekord und eine Nachrichtenwarteschlange.

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

Nachrichten umfassen Arbeit, die eine später Antwort erfordert, wie z.B. ein Widget, das die App auffordert, Daten zu synchronisieren.

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 die Aufgabe zu versagen, geben Sie anstatt 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 das bestehende Nachrichtensnapshot zurück.

Beenden Sie eine Native Sitzung

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

API Gruppen

Gruppe	APIs
Fähigkeit	areActivitiesSupported, getPluginVersion
SVG-Aktivitätslebenzyklus	startTemplateActivity, updateTemplateActivity, endTemplateActivity, getTemplateActivity, listTemplateActivities
SVG-Aktionen und Ereignisse	performTemplateAction, listTemplateEvents, acknowledgeTemplateEvents
Native-Widget-Sitzungen	startWidgetSession, updateWidgetSession, stopWidgetSession, getWidgetSession, listWidgetSessions
Native-Widget-Nachrichten	sendWidgetMessage, listWidgetMessages, acknowledgeWidgetMessages, completeWidgetMessage

Quelle der Wahrheit

Die vollständige Typenreferenz befindet sich im Plugin-Repository unter src/definitions.ts.

Fortsetzung von Getting Started

Wenn Sie Capgo verwenden Getting Started um native Plugin-Arbeiten zu planen, verbinden Sie es mit Verwendung von @capgo/capacitor-widget-kit für die native Fähigkeit in Verwendung von @capgo/capacitor-Widget-Kit, Capgo Plugin-Verzeichnis Capgo Plugin-Verzeichnis für den Produktworkflow in Capgo Plugin-Verzeichnis Capacitor Plugins von Capgo für die Implementierungsdetails in Capacitor Plugins durch Capgo Plugins hinzufügen oder aktualisieren für die Implementierungsdetails in Plugins hinzufügen oder aktualisieren und Ionic Enterprise-Plugin-Alternativen für das Produktworkflow in Ionic Enterprise-Plugin-Alternativen.