Kit de widgets plugin de Capacitor

Usando @capgo/capacitor-widget-kit

@capgo/capacitor-widget-kit permite a una aplicación Capacitor impulsar experiencias de WidgetKit y Live Activity de dos maneras:

• Renderizar superficies de plantilla SVG resueltas con cambios de marco, puntos de clic calientes y temporizadores de pausa/reanudar.
• 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

Utilice plantillas SVG cuando la superficie del widget se puede describir 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.

Las buenas opciones incluyen temporizadores de entrenamiento, tarjetas de estado de entrega, resultados de deportes, o cualquier interfaz 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 de widget se persisten como eventos. Lee y reconócelos 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 de Navegación Completa

Utilice sesiones de navegación completa 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 },
});

Programar Trabajo Asíncrono entre Widget y Aplicación

Los mensajes pueden fluir desde la aplicación a la widget o viceversa. Quedan pendientes hasta que sean reconocidos y completados.

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, complete el mensaje con un error:

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

Detener Sesiones de Manera Limpia

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

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

Nota de Configuración Nativa

Configure un grupo de App 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-kit-de-widget/
• Documentación: /docs/plugins/widget-kit/

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

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 los detalles de implementación en @capgo/capacitor-kit-de-widget, Getting Started para los 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 los detalles de implementación en Capacitor Plugins por Capgo, y Agregar o Actualizar Plugins para los detalles de implementación en Agregar o Actualizar Plugins.