Usando @capgo/capacitor-kit-de-widget

@capgo/capacitor-widget-kit permite que una aplicación Capacitor controle las experiencias de WidgetKit y Actividad en vivo de dos maneras:

Renderizar superficies de plantillas SVG resueltas con cambios de marco, puntos calientes de toque y temporizadores de pausa/reproducción.
Mantener el widget completamente nativo mientras la aplicación y el widget comparten un estado de sesión JSON y mensajes asíncronos.

Instalar

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

Cuándo usar plantillas SVG

Usar plantillas SVG cuando la superficie del widget puede describirse como SVG. La aplicación almacena una definición de plantilla, el puente nativo resuelve los lugares comunes y los toques del widget pueden mutar el estado más tarde.

Usa plantillas SVG cuando la superficie del widget puede describirse como SVG. La aplicación almacena una definición de plantilla, el puente nativo resuelve los lugares comunes y los toques del widget pueden mutar el estado más tarde. Buenos ajustes incluyen temporizadores de ejercicios, tarjetas de estado de entrega, puntuaciones de deportes, o cualquier interfaz de usuario compacta donde cambiar entre marcos nombrados es suficiente.

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

Gestionar Acciones De Widget En La Aplicación

Las acciones del widget se persisten como eventos. Lee y reconoce cuando la aplicación se reanude o después de un paso de sincronización de fondo.

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

¿Cuándo Usar Sesiones Nativas Completa?

Usa sesiones nativas completas cuando la interfaz de usuario del widget se construye mejor directamente en Swift, Kotlin o Java. Capacitor aún inicia y detiene la sesión, mantiene el estado compartido actualizado y programa el trabajo entre la aplicación y el 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 },
});

Cola Trabajo Asíncrono Entre Widget Y Aplicación

Los mensajes pueden fluir desde la aplicación al widget o viceversa. Quedan pendientes hasta que se reconocen y completan.

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

Si el trabajo falla, completa el mensaje con un error:

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

Cerrar Sesiones De Forma Limpia

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

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

Notas De Configuración Nativa

Para iOS WidgetKit y Actividades En Vivo, configura un Grupo de Aplicación en los objetivos de la aplicación y la extensión del widget, y establece CapgoWidgetKitAppGroup en ambos Info.plist archivos. Los botones interactivos requieren una extensión de widget que conecte el puente nativo proporcionado por el plugin y la intención de acción.

Referencia completa

GitHub: https://github.com/Cap-go/capacitor-kit-de-widget/
Documentación: /docs/plugins/widget-kit/

Kit de widget

Tutorial sobre Kit de Widget