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, hotspot di tocco e timer di pausa/riavvio.
• Mantieni il widget completamente nativo mentre l'app e il widget condividono uno stato di sessione JSON e messaggi asincroni.

Installare

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.

Le buone adatte 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 Pienamente Nativi

Usa le sessioni pienamente native quando l'interfaccia utente del widget è meglio costruita direttamente in Swift, Kotlin o Java. Capacitor inizia e ferma comunque la sessione, mantiene lo stato condiviso aggiornato e mette in coda il 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',
});

Chiudi 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

Per iOS WidgetKit e attività in tempo reale, 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 i dettagli di implementazione in @capgo/capacitor-kit di widget Inizio per i dettagli di implementazione in Inizio Directory dei plugin Capgo per il flusso di lavoro del prodotto in Directory dei plugin Capgo Plugin Capacitor di Capgo per i dettagli di implementazione in Plugin Capacitor di Capgo Aggiungere o aggiornare i plugin per i dettagli di implementazione in Aggiungere o aggiornare i plugin