Per iniziare

Installa

Puoi usare il nostro setup assistito dall'IA per installare il plugin. Aggiungi le skill Capgo al tuo strumento di IA usando il seguente comando:

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

Poi usa 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 questi comandi e segui le istruzioni specifiche per piattaforma qui sotto:

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

Importa

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

Avvio rapido

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

const result = await CapgoWidgetKit.areActivitiesSupported();
console.log(result);

Esempio: startTemplateActivity

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

const result = await CapgoWidgetKit.startTemplateActivity({
  definition: {
    id: 'id-123',
    layouts: {},
  },
  state: {},
});
console.log(result);

Esempio: startTemplateWidget

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

const result = await CapgoWidgetKit.startTemplateWidget({
  definition: {
    id: 'id-123',
    layouts: {},
  },
  state: {},
});
console.log(result);

Errori comuni

• Sync nativo: esegui bunx cap sync dopo gli aggiornamenti dei plugin.
• Fonte di verità: fidati src/definitions.ts nel repo GitHub.

Setup iOS

Per le Live Activities e le estensioni WidgetKit, configura prima l'app nativa:

• Usa iOS 17+ per i pulsanti interattivi delle Live Activity, quando possibile.
• Aggiungi NSSupportsLiveActivities all'app Info.plist quando si usa ActivityKit.
• Aggiungi lo stesso App Group sia al target dell'app che al target dell'estensione del widget.
• Imposta CapgoWidgetKitAppGroup in entrambi Info.plist file all'identificativo dell'App Group condiviso.

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

Controlla il Supporto

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

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

Opzione 1: SVG Template Activity

Usa questa modalità quando il widget può renderizzare SVG risolti. Il plugin gestisce lo stato, risolve i placeholder, applica le tap action, cambia i frame SVG e mantiene coerente lo stato del timer.

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 tramite il loro hotspot/action wiring. L'app può anche eseguirle direttamente:

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

Gestisci gli Eventi dei Widget

Le azioni emettono eventi in modo che l'app possa gestire le interazioni con i widget dopo il lancio o il resume:

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

Su iOS, i pulsanti delle widget extension possono invocare gli helper LiveActivityIntent inclusi nelCapgoTemplateActionIntent) che scrivono nello stesso log degli eventi. Questo è distinto dalle frasi di Siri shortcut o dall'app Shortcuts. Vedi Siri, Shortcuts e widget.

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 del frame scrivono l'id del frame attivo nello stato. Un layout può leggerlo tramite frameIdPath.

Operazione	Comportamento
set	Imposta un id frame specifico. Le stringhe semplici sono trattate come id frame letterali; {{...}} i template vengono risolti per primi.
next	Passa al frame successivo da frameIds o i frame dichiarati su surface.
previous	Passa al frame precedente.
toggle	Alterna tra i primi due frame disponibili, o tra il frame corrente e frameId.

Gli ID frame non validi vengono ignorati se la mutazione ha una lista di frame selezionabili nota, mantenendo lo stato allineato con la superficie renderizzata.

Mutazioni del Timer

Le mutazioni del timer agiscono su un timer nominato da definition.timers.

Operazione	Comportamento
start / restart	Ricomincia da zero usando la durata attuale.
pause	Memorizza il tempo trascorso e resetta startedAt.
resume	Riprendi solo i timer in pausa. I timer fermati rimarranno tali finché non verranno avviati o riavviati esplicitamente.
toggle	Metti in pausa un timer attivo o riprendi un timer in pausa.
reset	Resetta il tempo trascorso e torna allo stato idle.
stop	Cancella il progresso del runtime e segna il timer come fermo.
setDuration	Ricalcola lo stato dopo una modifica della durata.

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

Opzione 2: Sessione Widget Full-Native

Usa questa modalità quando la UI del widget è costruita in code nativo. Il plugin fornisce all'app e al widget un record 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 Widget Async

I messaggi gestiscono i task che richiedono una risposta successiva, 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 far fallire il job, passa error invece 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 Native

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

API Gruppi

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

Fonte di verità

Il riferimento completo ai tipi si trova nel repository del plugin all'indirizzo src/definitions.ts.

Continua da Getting Started

Se stai usando Per iniziare per pianificare il lavoro sui plugin nativi, collegalo a Utilizzo di @capgo/capacitor-widget-kit per la funzionalità nativa in Utilizzo di @capgo/capacitor-widget-kit, Directory dei plugin di Capgo per il workflow del prodotto nella Capgo Plugin Directory, Plugin Capacitor di Capgo per i dettagli di implementazione in Capacitor Plugins di Capgo, Aggiunta o aggiornamento dei plugin per i dettagli su come aggiungere o aggiornare i plugin, e Alternative ai plugin Ionic Enterprise per il workflow del prodotto in Alternative ai plugin Ionic Enterprise.