Getting Started

Installazione

Puoi utilizzare la nostra configurazione assistita dall'IA per installare il plugin. Aggiungi le Capgo abilità al tuo strumento di AI utilizzando il seguente comando:

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

Usa poi il seguente prompt:

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

Se preferisci la configurazione Manuale, installa il plugin eseguendo i seguenti comandi e segui le istruzioni specifiche del tuo platform:

bun add @capgo/capacitor-widget-kit
bunx cap sync

Importa

import { CapgoWidgetKit } from '@capgo/capacitor-widget-kit';

Configurazione iOS

Per le attività in tempo reale e le estensioni di WidgetKit, configurare l'app nativa per primo:

• Usare iOS 17+ per i pulsanti di attività in tempo reale interattivi quando possibile.
• Aggiungi NSSupportsLiveActivities alla app Info.plist quando si utilizza ActivityKit.
• Aggiungi lo stesso gruppo di app al target dell'app e al target dell'estensione del widget.
• Imposta CapgoWidgetKitAppGroup in entrambi i file l'identificatore del gruppo di applicazioni condiviso. Info.plist Copia negli appunti

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

Sezione intitolata “Verifica Supporto”

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

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

Sezione intitolata “Opzione 1: Modello di attività SVG”

Copia negli appunti

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

Esegui azioni dall'app

I widget nativi possono attivare le stesse azioni attraverso la loro configurazione hotspot/action. L'app può eseguirle direttamente:

await CapgoWidgetKit.performTemplateAction({
  activityId: activity.activityId,
  actionId: 'toggle-rest',
  sourceId: 'app-pause-play-button',
});

Processa Eventi Del Widget

Gli azioni emettono eventi in modo che l'app possa processare le interazioni del widget dopo l'avvio o il ripristino:

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

Aggiorna O Termina L'Attività

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

Mutazioni Del Frame

Le mutazioni di frame scrivono l'ID del frame attivo nello stato. Una layout può poi leggerlo con frameIdPath.

Operazione	Comportamento
set	Imposta un ID di frame specifico. Le stringhe piane vengono trattate come ID di frame letterali; i {{...}} sono risolti per primo.
next	Passa al prossimo frame da frameIds o dai frame dichiarati su surface.
previous	Passa al frame precedente.
toggle	Alternare tra i primi due frame disponibili, o tra il frame corrente e frameId.

ID di frame non validi vengono ignorati quando la mutazione ha una lista di frame selezionabili nota, quindi lo stato rimane allineato con la superficie visualizzata.

Mutazioni del timer

Mutazioni del timer mirano a un timer denominato da definition.timers.

Operazione	Comportamento
start / restart	Inizia da zero utilizzando la durata corrente.
pause	Memorizza il tempo trascorso e cancella startedAt.
resume	Riprendi solo i timer fermati. I timer fermati rimangono fermati fino a un'avvio esplicito o riavvio.
toggle	Ferma un timer in esecuzione o riprendi un timer fermato.
reset	Cancella il tempo trascorso e torna allo stato di attesa.
stop	Cancella il progresso di esecuzione e segnala il timer fermato.
setDuration	Ricalcola lo stato dopo un cambio di durata.

Le legature del timer sono disponibili per SVG come {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}, e campi correlati.

Opzione 2: Sessione di widget nativo a tutto tondo

Usa questo modo quando l'interfaccia utente del widget è costruita in code. Il plugin fornisce al'app e al widget un registro di sessione condiviso e una coda di messaggi.

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);

Messaggi di widget asincroni

I messaggi coprono il lavoro che richiede una risposta più tardi, come un widget che chiede all'app di sincronizzare i dati.

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

Per fallire il lavoro, passa error al posto di response:

await CapgoWidgetKit.completeWidgetMessage({
  messageId: message.messageId,
  error: 'Network unavailable',
});

completeWidgetMessage è idempotente. Se il messaggio è già completato o fallito, le chiamate ripetute restituiscono lo snapshot del messaggio esistente.

Interrompi una sessione nativa

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

API Gruppi

Gruppo	API
Capacità	areActivitiesSupported, getPluginVersion
Ciclo di vita dell'attività SVG	startTemplateActivity, updateTemplateActivity, endTemplateActivity, getTemplateActivity, listTemplateActivities
Azioni e eventi SVG	performTemplateAction, listTemplateEvents, acknowledgeTemplateEvents
Sessioni di widget nativo	startWidgetSession, updateWidgetSession, stopWidgetSession, getWidgetSession, listWidgetSessions
Messaggi di widget nativo	sendWidgetMessage, listWidgetMessages, acknowledgeWidgetMessages, completeWidgetMessage

Fonte di Verità

La referenza di tipo completa vive nel repository del plugin in src/definitions.ts.

Continua da Getting Started

Se stai utilizzando Getting Started per pianificare il lavoro di plugin nativo, connettilo con Utilizzando @capgo/capacitor-kit di widget per la capacità nativa in Utilizzando @capgo/capacitor-kit di widget, Directory del Plugin Capgo per il flusso di lavoro del prodotto in Directory del Plugin Capgo Plugin da Capacitor sviluppati da Capgo per i dettagli di implementazione in Plugin da Capacitor sviluppati da Capgo, Aggiunta o Aggiornamento di Plugin per i dettagli di implementazione in Aggiunta o Aggiornamento di Plugin, e Alternative per Plugin Enterprise di Ionic per il flusso di lavoro del prodotto in Alternative per Plugin Enterprise di Ionic.