Getting Started

Installieren

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 ActivityKit verwendet wird.
• Fügen Sie dem App-Target und dem Widget-Erweiterung-Target denselben App-Gruppen-Name hinzu.
• Setzen Sie CapgoWidgetKitAppGroup in beiden Info.plist Dateien 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 aufgelöste SVG rendern kann. Der Plugin speichert den Zustand, löst Platzhalter auf, anwendet Tastenaktionen, 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 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,
});

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

Framenmutationen

Framenmutationen schreiben den aktiven Frame-Id in den Zustand. Ein Layout kann ihn dann mit frameIdPath.

Operation	Verhalten
set	Einen bestimmten Frame-Id festlegen. Einfache Zeichenketten werden als wörtliche Frame-Ids behandelt; {{...}} Vorlagen 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 hin- und herwechseln, oder zwischen dem aktuellen Frame und frameId.

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

Timer-Mutationen

Timer-Mutationen richten sich auf einen benannten Timer von definition.timers.

Operation	Verhalten
start / restart	Mit der aktuellen Dauer von vorne beginnen.
pause	Verwenden Sie die verstrichene Zeit und löschen Sie sie. startedAt.
resume	Ersetzen Sie nur die angehaltene Timer. Gesteuerte Timer bleiben bis zu einem expliziten Start oder Neustart angehalten.
toggle	Pause einen laufenden Timer oder setzen Sie einen angehaltenen Timer fort.
reset	Löschen Sie die verstrichene Zeit und kehren Sie in den Idle-Modus zurück.
stop	Löschen Sie die Laufzeit und markieren Sie den Timer als gestoppt.
setDuration	Rechnen Sie den Status nach einer Daueränderung neu.

Timer-Bindings sind für SVG verfügbar als {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}, und verwandte Felder.

Option 2: Voll-Native Widget-Sitzung

Verwenden Sie diesen Modus, wenn die Widget-UI in native code. gebaut ist. Der Plugin gibt dem App und Widget einen gemeinsamen Sitzungsverlauf 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);

Async Widget Nachrichten

Die 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 die Aufgabe zu versagen, passen 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.

Stoppen Sie 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

Der vollständige Typenbezug befindet sich im Plugin-Repository bei src/definitions.ts.

Weitermachen von Getting Started

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