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

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 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-Target und dem Widget-Extension-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-Vorlage für Activity

Verwenden Sie diesen Modus, wenn das Widget die gelösten SVG rendern kann. Das 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 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, 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. Plain Strings werden als Literal-Frame-Ids behandelt; {{...}} Vorlagen werden zuerst gelöst.
next	Zum nächsten Frame wechseln von frameIds oder den auf surface.
previous	Zum vorherigen Frame wechseln.
toggle	Zwischen dem ersten und dem zweiten verfügbaren Frame, oder zwischen dem aktuellen Frame und frameId.

Ungültige Rahmeneinheiten werden ignoriert, wenn die Mutation eine bekannte Liste auswählbarer 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 pausierten Timer wieder aufnehmen. Gepauste Timer bleiben bis zu einem expliziten Start oder Neustart gestoppt.
toggle	Ein laufender 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	Rekalkulieren Sie den Status nach einer Änderung der Dauer.

Timer-Bindungen sind für SVG 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. Das Plugin gibt dem App und Widget einen gemeinsamen Sitzungsrecord 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, geben 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.

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 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 den Produktworkflow in Ionic Enterprise Plugin Alternativen.