Kit di widget

Utilizzando @capgo/capacitor-widget-kit

@capgo/capacitor-widget-kit Consente a un'app Capacitor di guidare le esperienze di WidgetKit e Live Activity in due modi:

• Rendere le superfici di template SVG risolte con il passaggio di frame, punti di caldo di tocco e timer di pausa/riavvio.
• Tenere il widget completamente nativo mentre l'app e il widget condividono lo stato di sessione JSON e messaggi asincroni.

Installa

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

When Usare Template SVG

Usa le template SVG quando la superficie del widget può essere descritta come SVG. L'applicazione memorizza una definizione di template, il ponte nativo risolve i placeholder e i tocchi del widget possono mutare lo stato in seguito.

Buoni adatti includono timer di allenamento, carte dello stato di consegna, punteggi sportivi o qualsiasi interfaccia utente compatto dove cambiare tra frame denominati è sufficiente.

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

const { activity } = await CapgoWidgetKit.startTemplateActivity({
  activityId: 'session-1',
  state: {
    title: 'Chest Day',
    frame: 'summary',
    restDurationMs: 90000,
  },
  definition: {
    id: 'workout-card',
    timers: [{ id: 'rest', durationPath: 'state.restDurationMs' }],
    actions: [
      {
        id: 'next-frame',
        frameMutations: [{ op: 'next', path: 'frame', surface: 'lockScreen' }],
      },
      {
        id: 'toggle-rest',
        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>`,
          },
        ],
      },
    },
  },
});

Gestisci Azioni del Widget nell'App

Gli azioni del widget sono persistite come eventi. Leggi e riconosci quando l'app si riavvia o dopo un passo di sincronizzazione in background.

const { events } = await CapgoWidgetKit.listTemplateEvents({
  activityId: activity.activityId,
  unacknowledgedOnly: true,
});

for (const event of events) {
  console.log(event.actionId, event.state, event.timers);
}

await CapgoWidgetKit.acknowledgeTemplateEvents({ activityId: activity.activityId });

When Usare Sessioni a Pieno-Nativo

Usa le sessioni a pieno-nativo quando l'interfaccia utente del widget è meglio costruita direttamente in Swift, Kotlin o Java. Capacitor inizia e ferma la sessione, mantiene lo stato condiviso aggiornato e invia lavoro tra l'app e il widget code.

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

Incollo Lavoro Asincrono tra Widget e App

I messaggi possono fluire dall'app al widget o dal widget all'app. Restano in attesa di conferma e completamento.

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

Se il lavoro fallisce, completa il messaggio con un errore:

await CapgoWidgetKit.completeWidgetMessage({
  messageId: message.messageId,
  error: 'Sync failed',
});

Ferma Sessioni Pulitamente

await CapgoWidgetKit.endTemplateActivity({
  activityId: activity.activityId,
  state: { title: 'Workout complete', frame: 'summary' },
});

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

Note di configurazione nativa

For iOS WidgetKit e attività in tempo reale, configurare un gruppo di applicazione sulle impostazioni dell'app e dell'estensione widget e impostare CapgoWidgetKitAppGroup in entrambi Info.plist i file. I pulsanti interattivi richiedono un'estensione widget che collega il ponte nativo fornito dal plugin e l'intento di azione.

Riferimento completo

• GitHub: https://github.com/Cap-go/capacitor-widget-kit/
• Documentazione: /docs/plugins/widget-kit/

Continua da Utilizzo di @capgo/capacitor-widget-kit

Se stai utilizzando Utilizzo di @capgo/capacitor-widget-kit per pianificare il lavoro del plugin nativo, connettilo con @capgo/capacitor-widget-kit per i dettagli di implementazione in @capgo/capacitor-kit di widget Iniziare per i dettagli di implementazione in Iniziare Capgo Directory dei Plugin per il flusso di lavoro del prodotto in Capgo Directory dei Plugin Capacitor Plugin da Capgo per i dettagli di implementazione in Capacitor Plugin da Capgo, e Aggiungere o Aggiornare i Plugin per i dettagli di implementazione in Aggiungere o Aggiornare i Plugin.