Kit de widget

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:

• Renderiza superficies de plantillas SVG resueltas con cambios de marco, puntos de calor de toque y temporizadores de pausa/reanudar.
• Mantenga el widget completamente nativo mientras la aplicación y el widget comparten un estado de sesión JSON compartido y mensajes asíncronos.

Instalar

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

When to Use Templates SVG

Utiliza 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.

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

Gestiona las acciones del widget en la aplicación.

Las acciones del 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 });

When to Use Sessions Nativas Completa

Utiliza sesiones nativas completas 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 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 el trabajo asíncrono entre el widget y la aplicación.

Los mensajes pueden fluir de la aplicación al widget o del widget a la aplicación. Quedan pendientes hasta que se reconocen y se 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',
});

Detén las sesiones limpiamente.

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

For 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 in ambos Info.plist archivos. Los botones interactivos requieren una extensión de widget que conecte la puente nativa proporcionada 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-widget-kit

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