Einstieg

Installieren

Sie können unsere AI-gestützte Einrichtung verwenden, um das Plugin zu installieren. Fügen Sie den Capgo-Fähigkeiten Ihre AI-Werkzeug hinzufügen, indem Sie die folgende Befehl ausführen:

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

Verwenden Sie dann die folgende Anfrage:

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

Wenn Sie die manuelle Einrichtung bevorzugen, installieren Sie das Plugin, indem Sie die folgenden Befehle ausführen und folgen Sie den unten angegebenen Plattform-spezifischen Anweisungen:

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 die native App zuerst:

• Verwenden Sie iOS 17+ für interaktive Live-Aktivitätsknöpfe, wenn möglich.
• Hinzufügen NSSupportsLiveActivities zur App Info.plist wenn Sie ActivityKit verwenden.
• Fügen Sie dem gleichen App-Gruppen-Element zur App-Ziel und zur Widget-Erweiterungs-Ziel hinzu.
• Setzen Sie CapgoWidgetKitAppGroup in beiden Info.plist Dateien auf den gemeinsamen App-Gruppen-Bezeichner.

<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 gelösten SVG rendern kann. Der Plugin speichert den Zustand, löst Platzhalter auf, legt Tastenaktionen zu, wechselt zwischen 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 aus der App ausführen

Nativ-Widgets können die gleichen Aktionen über ihre Hotspot/Aktion-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',
});

Widgetereignisse verarbeiten

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

Aktualisieren oder beenden Sie die Aktivität

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 bestimmte Frame-ID. Plain-Strings werden als wörtliche Frame-IDs behandelt; {{...}} Templates werden zuerst aufgelöst.
next	Zum nächsten Frame wechseln von frameIds oder den auf surface.
previous	Zum vorherigen Frame wechseln.
toggle	Zwischen den ersten beiden verfügbaren Frames, oder zwischen dem aktuellen Frame und frameId.

Ungültige Frame-IDs werden ignoriert, wenn die Mutation eine bekannte Auswahlmöglichkeit für Frames hat, daher bleibt der Zustand mit der renderierten Oberfläche im Einklang.

Timer-Veränderungen

Timer-Veränderungen richten sich auf einen benannten Timer von definition.timers.

Operation	Verhalten
start / restart	Von Null aus starten, unter Verwendung der aktuellen Dauer.
pause	Gelaufene Zeit speichern und löschen startedAt.
resume	Pause nur laufende Timer. Gepauste Timer bleiben bis zu einem expliziten Start oder Neustart stehen.
toggle	Ein laufender Timer pausen oder einen pausierten Timer wieder in Gang setzen.
reset	Zeitablauf löschen und in den Idle-Modus zurückkehren.
stop	Laufzeitfortschritt löschen und den Timer als gestoppt markieren.
setDuration	Status nach einer Laufzeitänderung neu berechnen.

Timer-Bindings stehen für SVG als {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}, und verwandte Felder zur Verfügung.

Option 2: Voll-Native Widget-Sitzung

Verwenden Sie diesen 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 behandeln Arbeit, die eine späterige Antwort erfordert, wie 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 den Job zu scheitern, ü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, returnen wiederholte Aufrufe das bestehende Nachrichtensnapshot.

Stoppe eine Native-Sitzung

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

API-Gruppen

Gruppe	APIs
Fähigkeit	areActivitiesSupported, getPluginVersion
SVG-Aktivitätslebenszyklus	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 bei src/definitions.ts.

__CAPGO_KEEP_0__

If Sie native Plugins verwenden Anleitung zum Starten um native Plugin-Arbeiten zu planen, verbinden Sie es mit Mit @capgo/capacitor-widget-kit um die native Fähigkeit in Mit @capgo/capacitor-widget-kit zu verwenden, Capgo Plugin-Verzeichnis um den Produktworkflow in Capgo Plugin-Verzeichnis zu verwenden, Capacitor Plugins von Capgo um die Implementierungsdetails in Capacitor Plugins von Capgo zu verwenden, Hinzufügen oder Aktualisieren von Plugins um die Implementierungsdetails in Hinzufügen oder Aktualisieren von Plugins zu verwenden, und Ionische Enterprise-Plugin-Alternativen für das Produktworkflow in Ionic Enterprise Plugin Alternativen.