Getting Started

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 plugin ejecutando los siguientes comandos y sigue las instrucciones específicas del 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, configure la aplicación nativa primero:

• Utilice iOS 17+ para botones de actividad en vivo interactivos cuando sea posible.
• Agregar NSSupportsLiveActivities a la aplicación Info.plist cuando se utilice ActivityKit.
• Agregar el mismo grupo de aplicación a la meta de la aplicación y a la meta de la extensión de widget.
• Configura CapgoWidgetKitAppGroup en ambos Info.plist archivos al identificador de grupo de aplicaciones 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

Utiliza este modo cuando el widget puede renderizar SVG resuelto. El plugin almacena el estado, resuelve los reemplazos, aplica las acciones de toque, cambia las marcas 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 configuración 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 los widgets 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 layout puede leerlo 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; los {{...}} se resuelven primero.
next	Ir al siguiente marco desde frameIds o los marcos declarados en surface.
previous	Ir al marco anterior.
toggle	Alternar entre los dos marcos disponibles, o entre el marco actual y frameId.

Los ids de marco inválidos se ignoran cuando la mutación tiene una lista de marcos seleccionables conocida, por lo que el estado se alinea con la superficie renderizada.

Mutaciones de temporizador

Mutaciones de temporizador apuntan a un temporizador con nombre desde definition.timers.

Operación	Comience desde cero utilizando la duración actual.
start / restart	Almacene el tiempo transcurrido y elimine
pause	Reanude solo los temporizadores pausados. Los temporizadores detenidos permanecen detenidos hasta que se inicie explícitamente o se reinicie. startedAt.
resume	Pausar un temporizador en ejecución o reanudar un temporizador pausado.
toggle	Elimine el tiempo transcurrido y regrese a estado de inactividad.
reset	Elimine el progreso de tiempo de ejecución y marque el temporizador detenido.
stop	Recomputar el estado después de un cambio de duración.
setDuration	Las vinculaciones de temporizador están disponibles para SVG como

, y campos relacionados. {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}]} (12 strings) (Note: The translations are provided in the same order as the input texts) (Note: The protected tokens are preserved as is in the translations) (Note: The placeholders __CAPGO_KEEP_0__ are not present in the input texts) (Note: The translations are provided in Spanish as per the target language specified in the input) (Note: The translations are provided in a natural and culturally adapted way for the Spanish user context) (Note: The translations preserve the brand names, product names, developer terms, URLs, code identifiers, file paths, package names, language codes, numbers, punctuation, and whitespace meaning) (Note: The translations do not translate or transliterate literal tokens such as Cloudflare, Capacitor, GitHub, Capgo, code, API, SDK, CLI, npm, bun) (Note: The translations are provided in a JSON object with exactly one key named

Opción 2: Widget de Sesión Completa-Nativa

Utilice este modo cuando la interfaz de usuario del widget se construye en code. El plugin proporciona un registro de sesión compartido para la aplicación y el widget, así como 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);

Mensaje Asíncrono del Widget

Los mensajes cubren tareas que requieren una respuesta posterior, como un widget que solicita a la aplicación sincronizar 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, pasar error en lugar de response:

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

completeWidgetMessage es idípoto. Si el mensaje ya está completado o 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
Ciclo de vida de actividades SVG	startTemplateActivity, updateTemplateActivity, endTemplateActivity, getTemplateActivity, listTemplateActivities
Acciones y eventos SVG	performTemplateAction, listTemplateEvents, acknowledgeTemplateEvents
Sesiones de widgets nativos	startWidgetSession, updateWidgetSession, stopWidgetSession, getWidgetSession, listWidgetSessions
Mensaje de widgets nativos	sendWidgetMessage, listWidgetMessages, acknowledgeWidgetMessages, completeWidgetMessage

Fuente de Verdad

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

Sigue adelante desde Getting Started

Si estás utilizando Getting Started para planificar el trabajo de plugin nativo, conecta con Usando @capgo/capacitor-kit de widget para la capacidad nativa en Usando @capgo/capacitor-kit de widget, Directorio del plugin Capgo para el flujo de trabajo del producto en Directorio del plugin Capgo Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by 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.