Kit di widget

Utilizzando @capgo/capacitor-widget-kit

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

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

Installa

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

Quando Usare Template SVG

Usa i 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 esempi includono timer di allenamento, carte di stato di consegna, punteggi di sport, 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

Le azioni del widget sono persistite come eventi. Leggi e riconosci le azioni 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 });

Quando Usare Sessioni Full-Native

Usa sessioni full-native 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 },
});

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

Nota di configurazione del setup nativo

Per iOS WidgetKit e attività in diretta, configurare un gruppo di applicazione sulle destinazioni 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 il dettaglio di implementazione in @capgo/capacitor-kit di widget Inizia per il dettaglio di implementazione in Inizia 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, e Aggiungi o Aggiorna Plugin per il dettaglio di implementazione in Aggiungi o Aggiorna Plugin