Kit de widget

Usando @capgo/capacitor-kit-de-widget

@capgo/capacitor-widget-kit permite a una app Capacitor controlar experiencias de WidgetKit y Live Activity de dos maneras:

• Renderiza superficies de plantillas SVG resueltas con cambios de marco, puntos calientes de toque y temporizadores de pausa/reproducción.
• Mantén el widget completamente nativo mientras la app 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

Usa plantillas SVG cuando la superficie del widget puede describirse como SVG. La app almacena una definición de plantilla, la puente nativa resuelve marcadores, y los toques del widget pueden mutar el estado más tarde.

Los ajustes adecuados incluyen temporizadores de entrenamiento, 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 App

Las acciones de widget se persisten como eventos. Lee y reconócelas cuando la app 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 de Navegación Completa

Usa sesiones de navegación completa cuando la interfaz de usuario del widget es mejor construida 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 app 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 },
});

Programar Trabajo Asíncrono entre Widget y App

Los mensajes pueden fluir desde la aplicación a la widget o viceversa. Quedan pendientes hasta que se confirman 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 la tarea falla, complete el mensaje con un error:

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

Detener Sesiones Limpiamente

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, configure un Grupo de Aplicación en los objetivos de la aplicación y la extensión de widget, y establezca 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-widget-kit/
• Documentación: /docs/plugins/widget-kit/

Sigue adelante desde Usando @capgo/capacitor-widget-kit

Si estás utilizando Usando @capgo/capacitor-kit-de-widget para planificar el trabajo de plugin nativo, conecta con @capgo/capacitor-kit-de-widget para obtener detalles de implementación en @capgo/capacitor-kit-de-widget, Inicio para obtener detalles de implementación en Inicio, Capgo Directorio de Plugins para el flujo de trabajo del producto en Capgo Directorio de Plugins, Capacitor Plugins por Capgo para obtener detalles de implementación en Capacitor Plugins por Capgo, y Agregar o Actualizar Plugins para los detalles de implementación en la sección de Agregar o Actualizar Plugins.