Getting Started

Installieren

Sie können unsere KI-gestützte Einrichtung verwenden, um den Plugin zu installieren. Fügen Sie die Capgo-Fähigkeiten zu Ihrem KI-Tool hinzu, 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

Import

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ätsknöpfe, wenn möglich.
• Hinzufügen NSSupportsLiveActivities zur App Info.plist wenn Sie ActivityKit verwenden.
• Fügen Sie dem App-Target und dem Widget-Erweiterungs-Target denselben App-Gruppen hinzu.
• Setzen Sie in beiden Dateien den gemeinsamen App-Gruppen-Bezeichner. CapgoWidgetKitAppGroup Zum Clipboard kopieren Info.plist Überprüfen Sie die Unterstützung

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

Zum Clipboard kopieren

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

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

Verwenden Sie diesen Modus, wenn das Widget die gelöste SVG rendern kann. Der Plugin speichert den Zustand, löst Platzhalter auf, anwendet Tastenaktionen, wechselt SVG-Frames und hält den Timerzustand konsistent.

Aktionen aus der App ausführen

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

__CAPGO_KEEP_0__

Nativ-Widgets können die gleichen 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-Ereignisse verarbeiten

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

Aktualisieren oder die Aktivität 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' },
});

Fensteränderungen

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

Operation	Verhalten
set	Setze einen bestimmten Frame-Id. Normale Zeichenketten werden als wörtliche Frame-Ids behandelt; {{...}} Vorlagen werden zuerst aufgelöst.
next	Gehe zum nächsten Frame von frameIds oder den Frames, die auf surface.
previous	Gehe zum vorherigen Frame.
toggle	Schalte 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, so bleibt der Zustand mit der gerenderten Oberfläche im Einklang.

Timer Mutationen

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

Operation	Verhalten
start / restart	Mit der aktuellen Dauer beginnen, indem Sie von Null aus starten.
pause	Zeit, die seit dem Start vergangen ist, speichern und startedAt.
resume	Warten Sie, bis ein Timer wieder aufgenommen wird. Ein gestoppter Timer bleibt bis zu einem expliziten Start oder Neustart gestoppt.
toggle	Einen laufenden Timer pausieren oder einen pausierten Timer wieder aufnehmen.
reset	Die seit dem Start vergangene Zeit löschen und in den Idle-Modus zurückkehren.
stop	Die Laufzeit fortschreiten und den Timer als gestoppt markieren.
setDuration	Status nach einer Änderung der Dauer neu berechnen.

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

Option 2: Voll-Native-Widget-Sitzung

Wählen Sie diese Modus, wenn die Widget-UI in native code. 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);

Asynchrone Widget-Nachrichten

Nachrichten umfassen Arbeit, die eine späterige 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 den Job zu versagen, ü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, wiederholte Aufrufe geben das bestehende Nachrichtensnapshot zurück.

Stop 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

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

Weitermachen von Getting Started

Wenn Sie native Plugin-Arbeiten planen, verbinden Sie es mit Getting Started um native Plugin-Arbeiten 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 by Capgo for the implementation detail in Capacitor Plugins by Capgo, Plugins hinzufügen oder aktualisieren für die Implementierungsdetails in Plugins hinzufügen oder aktualisieren, und Alternativen zu Ionic Enterprise Plugins für den Produktworkflow in Alternativen zu Ionic Enterprise Plugins.