Anleitung

Installieren

Sie können unsere AI-gestützte Einrichtung verwenden, um das Plugin zu installieren. Fügen Sie die Capgo-Fähigkeiten zu Ihrem KI-Tool hinzu, indem Sie die folgende Befehlszeile verwenden:

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

Dann verwenden Sie 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 eine manuelle Einrichtung bevorzugen, installieren Sie das Plugin, indem Sie die folgenden Befehle ausführen und die unten 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-Schaltflächen, wenn möglich.
• Hinzufügen NSSupportsLiveActivities zum App Info.plist wenn Sie ActivityKit verwenden.
• Fügen Sie dem App-Ziel und dem Widget-Erweiterungsziel denselben App-Gruppen-Name zu.
• 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-Template-Aktivität

Verwenden Sie diesen Modus, wenn das Widget die aufgelöste SVG rendern kann. Das 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',
});

Verarbeiten Sie Ereignisse des Widgets

Aktionen senden Ereignisse aus, 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,
});

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 einen bestimmten Frame-Id. Texte 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 Rahmeneinheiten werden ignoriert, wenn die Mutation eine bekannte Auswahlliste von Rahmeneinheiten hat, sodass sich der Zustand mit der renderierten Oberfläche synchronisiert.

Timer-Mutationen

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

Operation	Verhalten
start / restart	Mit der aktuellen Dauer beginnen, indem man von Null aus startet.
pause	Zeit, die seit dem Start vergangen ist, speichern und löschen startedAt.
resume	Nur die unterbrochenen Timer wieder aufnehmen. Unterbrochene Timer bleiben bis zu einem expliziten Start oder Neustart unterbrochen.
toggle	Ein laufender Timer pausieren oder einen unterbrochenen Timer wieder aufnehmen.
reset	Die seit dem Start vergangene Zeit löschen und in den Idle-Modus zurückkehren.
stop	Die Laufzeit des Timers löschen und den Timer als gestoppt kennzeichnen.
setDuration	Nach einer Änderung der Dauer wird der Status neu berechnet.

Timer-Bindungen sind für SVG als {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}, und damit verbundene Felder.

Option 2: Vollständige native Widget-Sitzung

Verwenden Sie diesen Modus, wenn die Widget-UI in native code erstellt 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ä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 die Aufgabe 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 liefern das bestehende Nachrichtensnapshot zurück.

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.

Weitermachen von Getting Started

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