Iniziato

Installa

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

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

Poi utilizza 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 l'installazione manuale, installa il plugin eseguendo i seguenti comandi e segui le istruzioni specifiche per la piattaforma riportate di seguito:

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

Importa

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

Configurazione per iOS

Per le attività live e le estensioni di WidgetKit, configura l'app nativa per primo:

• Utilizza iOS 17+ per i pulsanti di attività live 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.
• Impostare CapgoWidgetKitAppGroup in entrambi Info.plist i file al riconoscimento identificativo del gruppo di app condiviso.

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

Verifica il Supporto

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

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

Opzione 1: Modello SVG di attività

Eseguire questo modo quando il widget può renderizzare SVG risolto. Il plugin memorizza lo stato, risolve i placeholder, applica le azioni di tap, passa le frame SVG e mantiene lo stato del timer coerente.

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

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

Processare Eventi Del Widget

Gli azioni emettono eventi affinché l'app possa processare le interazioni del widget dopo il lancio o la ripresa:

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

Aggiornare O Terminare 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 di frame

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

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

I frame id 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

Le mutazioni del timer mirano a un timer denominato da definition.timers.

Operazione	Comportamento
start / restart	Inizia da zero utilizzando la durata corrente.
pause	Mantieni il tempo trascorso e cancella startedAt.
resume	Riprendi solo i timer fermati. I timer fermati rimangono fermati fino a un avvio esplicito o un riavvio.
toggle	Fermati 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 come fermato.
setDuration	Ricalcola lo stato dopo un cambio di durata.

Il binding del timer è disponibile per SVG come {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}, e i relativi campi.

Opzione 2: Sessione del widget nativo a piena capacità

Usa questo modo quando l'interfaccia del widget è costruita in code nativo. 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 del widget asincroni

I messaggi coprono il lavoro che richiede 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 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
Vita ciclo dell'attività SVG	startTemplateActivity, updateTemplateActivity, endTemplateActivity, getTemplateActivity, listTemplateActivities
Azioni e eventi SVG	performTemplateAction, listTemplateEvents, acknowledgeTemplateEvents
Sessioni widget native	startWidgetSession, updateWidgetSession, stopWidgetSession, getWidgetSession, listWidgetSessions
Messaggi widget native	sendWidgetMessage, listWidgetMessages, acknowledgeWidgetMessages, completeWidgetMessage

Fonte di verità

La riferimento completo del tipo vive nel repository del plugin a src/definitions.ts.

Continua da Iniziare

Se stai utilizzando Iniziare per pianificare il lavoro di plugin native, connettilo con Utilizzando @capgo/capacitor-widget-kit per la capacità nativa in Utilizzare @capgo/capacitor-kit di widget Capgo Directory dei Plugin per il flusso di lavoro del prodotto in Capgo Directory dei Plugin Capacitor Plugin da Capgo per il dettaglio di implementazione in Capacitor Plugin da Capgo Aggiungere o Aggiornare i Plugin per il dettaglio di implementazione in Aggiungere o Aggiornare i Plugin, e Alternative Plugin Enterprise Ionic per il flusso di lavoro del prodotto in Alternative Plugin Enterprise Ionic