Inicio

Instalar

Puedes utilizar nuestra configuración asistida por IA para instalar el plugin. Agrega las Capgo habilidades a tu herramienta de IA utilizando el siguiente comando:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Luego utiliza el siguiente prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-widget-kit` plugin in my project.

Si prefieres la configuración manual, instala el complemento ejecutando los siguientes comandos y sigue las instrucciones específicas de la plataforma a continuación:

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

Importar

import { CapgoWidgetKit } from '@capgo/capacitor-widget-kit';

Configuración de iOS

Para actividades en vivo y extensiones de WidgetKit, configura la aplicación nativa primero:

• Utiliza iOS 17+ para botones de actividad en vivo interactivos siempre que sea posible.
• Agregar NSSupportsLiveActivities al la aplicación Info.plist cuando se utiliza ActivityKit.
• Agregar el mismo grupo de aplicación a la aplicación objetivo y el objetivo de la extensión de widget.
• Configurar CapgoWidgetKitAppGroup en ambos Info.plist archivos al identificador del grupo de aplicación compartido.

<key>CapgoWidgetKitAppGroup</key>
<string>group.app.capgo.widgetkit.exampleapp.widgetkit</string>

Ver Soporte

const { supported, reason } = await CapgoWidgetKit.areActivitiesSupported();

if (!supported) {
  console.log('WidgetKit bridge unavailable:', reason);
}

Opción 1: Plantilla de SVG de Actividad

Utilice este modo cuando el widget pueda renderizar SVG resuelto. El plugin almacena el estado, resuelve marcadores, aplica acciones de toque, cambia marcos de SVG y mantiene el estado del temporizador consistente.

const { activity } = await CapgoWidgetKit.startTemplateActivity({
  activityId: 'workout-session-1',
  openUrl: 'myapp://workout/session-1',
  state: {
    title: 'Chest Day',
    frame: 'summary',
    restDurationMs: 90000,
  },
  definition: {
    id: 'workout-card',
    timers: [
      {
        id: 'rest',
        durationPath: 'state.restDurationMs',
      },
    ],
    actions: [
      {
        id: 'next-frame',
        eventName: 'widget.frame.changed',
        frameMutations: [
          {
            op: 'next',
            path: 'frame',
            surface: 'lockScreen',
          },
        ],
      },
      {
        id: 'toggle-rest',
        eventName: 'widget.timer.toggled',
        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>`,
          },
        ],
      },
    },
  },
});

Ejecutar Acciones Desde La Aplicación

Los widgets nativos pueden disparar las mismas acciones a través de su cableado de hotspot/acción. La aplicación también puede ejecutarlas directamente:

await CapgoWidgetKit.performTemplateAction({
  activityId: activity.activityId,
  actionId: 'toggle-rest',
  sourceId: 'app-pause-play-button',
});

Procesar Eventos De Widget

Las acciones emiten eventos para que la aplicación pueda procesar las interacciones de widget después de lanzar o reanudar:

const { events } = await CapgoWidgetKit.listTemplateEvents({
  activityId: activity.activityId,
  unacknowledgedOnly: true,
});

for (const event of events) {
  console.log('Widget event:', event.eventName, event.state, event.timers);
}

await CapgoWidgetKit.acknowledgeTemplateEvents({
  activityId: activity.activityId,
});

Actualizar O Finalizar La Actividad

await CapgoWidgetKit.updateTemplateActivity({
  activityId: activity.activityId,
  state: {
    title: 'Back Day',
    frame: 'summary',
    restDurationMs: 120000,
  },
});

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

Mutaciones de marco

Las mutaciones de marco escriben el id del marco activo en el estado. Un diseño puede leerlo luego con frameIdPath.

Operación	Comportamiento
set	Establecer un id de marco específico. Las cadenas de texto planas se tratan como ids de marco literales; {{...}} se resuelven las plantillas primero.
next	Moverse al siguiente marco desde frameIds o los marcos declarados en surface.
previous	Moverse al marco anterior.
toggle	Alternar entre los dos marcos disponibles, o entre el marco actual y frameId.

Se ignoran los IDs de marcos inválidos cuando la mutación tiene una lista de marcos seleccionables conocida, por lo que el estado se mantiene alineado con la superficie renderizada.

Mutaciones de temporizador

Las mutaciones de temporizador apuntan a un temporizador con nombre de definition.timers.

Operación	Comportamiento
start / restart	Comience desde cero utilizando la duración actual.
pause	Almacene el tiempo transcurrido y elimine startedAt.
resume	Reanude solo los temporizadores pausados. Los temporizadores detenidos permanecen detenidos hasta que se inicia explícitamente o se reinicia.
toggle	Pausa un temporizador en ejecución o reanuda un temporizador pausado.
reset	Elimine el tiempo transcurrido y regrese a estado de inactividad.
stop	Elimine el progreso de tiempo de ejecución y marque el temporizador como detenido.
setDuration	Recomputar el estado después de un cambio de duración.

Las ataduras de temporizador están disponibles para SVG como {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}, y campos relacionados.

Opción 2: Sesión de Widget de Natividad Completa

Utilice este modo cuando la interfaz de usuario del widget se construye en nativo code. El complemento proporciona al aplicación y al widget un registro de sesión compartido y una cola de mensajes.

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

const { sessions } = await CapgoWidgetKit.listWidgetSessions();
console.log('Known widget sessions:', sessions);

Mensajes de Widget Asíncronos

Los mensajes cubren trabajo que requiere una respuesta posterior, como un widget que solicita a la aplicación que sincronice datos.

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

Para fallar el trabajo, pase error en lugar de response:

await CapgoWidgetKit.completeWidgetMessage({
  messageId: message.messageId,
  error: 'Network unavailable',
});

completeWidgetMessage es idempotente. Si el mensaje ya está completado o ha fallado, las llamadas repetidas devuelven el snapshot de mensaje existente.

Detener una Sesión Nativa

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

API Grupos

Grupo	APIs
Capacidad	areActivitiesSupported, getPluginVersion
SVG del ciclo de vida de la actividad	startTemplateActivity, updateTemplateActivity, endTemplateActivity, getTemplateActivity, listTemplateActivities
Acciones y eventos SVG	performTemplateAction, listTemplateEvents, acknowledgeTemplateEvents
Sesiones de widget nativo	startWidgetSession, updateWidgetSession, stopWidgetSession, getWidgetSession, listWidgetSessions
Mensajes de widget nativo	sendWidgetMessage, listWidgetMessages, acknowledgeWidgetMessages, completeWidgetMessage

Fuente de Verdad

La referencia de tipo completa se encuentra en el repositorio del plugin en src/definitions.ts.

Sigue adelante desde Inicio

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