Kit di widget

Utilizzando @capgo/capacitor-widget-kit

@capgo/capacitor-widget-kit Consente a un'app Capacitor di guidare le esperienze di WidgetKit e di attività in tempo reale in due modi:

• Rendere le superfici di template SVG risolte con il passaggio di frame, hotspot di tocco e timer di pausa/riavvio.
• Conserva 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

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 esempi includono timer di allenamento, carte dello stato di consegna, punteggi sportivi o qualsiasi interfaccia utente compatto dove è sufficiente spostarsi tra frame denominati.

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

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 la sessione, mantiene lo stato condiviso corrente 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 },
});

Invia 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

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-kit-di-widget/
• Documentazione: /docs/plugins/widget-kit/

Prosegui con l'uso di @capgo/capacitor-kit-di-widget

Se stai utilizzando L'uso di @capgo/capacitor-kit-di-widget per pianificare il lavoro del plugin nativo, connettilo con @capgo/capacitor-kit-di-widget per i dettagli di implementazione in @capgo/capacitor-kit di widget Avvio rapido per i dettagli di implementazione in Avvio rapido 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, e Aggiungere o aggiornare i plugin per i dettagli di implementazione in Aggiungere o aggiornare i plugin.