Getting Started

Instalar

Puede utilizar nuestra configuración asistida por IA para instalar el plugin. Agregue las Capgo habilidades a su herramienta de IA utilizando el siguiente comando:

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

Luego utilice la siguiente solicitud:

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

Si prefiere la configuración manual, instale el complemento ejecutando los siguientes comandos y siga 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';

iOS Setup

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

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

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

Verificar el 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 complemento almacena el estado, resuelve los reemplazos, aplica las acciones de toque, cambia las 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 desencadenar 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 del Widget

Las acciones emiten eventos para que la aplicación procese las interacciones de los widgets después del arranque o reinicio.

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 terminar 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; {{...}} plantillas se resuelven primero.
next	Mover a la siguiente imagen desde frameIds o las imágenes declaradas en surface.
previous	Mover a la imagen anterior.
toggle	Alternar entre las dos primeras imágenes disponibles, o entre la imagen actual y frameId.

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

Mutaciones de temporizador

Timer mutations apuntan a un temporizador nombrado desde definition.timers.

Operación	Comportamiento
start / restart	Comenzar desde cero utilizando la duración actual.
pause	Almacenar el tiempo transcurrido y borrar startedAt.
resume	Reanuda solo los temporizadores pausados. Los temporizadores detenidos permanecen detenidos hasta un arranque explícito o reinicio.
toggle	Pausa un temporizador en ejecución o reanuda un temporizador pausado.
reset	Clear elapsed time and return to idle.
stop	Restablecer el progreso de ejecución y marcar el temporizador detenido.
setDuration	Recomputar el estado después de un cambio de duración.

Timer bindings are available to SVG as {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}y campos relacionados.

Sesión de Widget Completa-Nativa

Utilice este modo cuando la interfaz de usuario del widget se construye en 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 Asincrónicos

Los mensajes cubren el trabajo que requiere 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, pasa 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 falló, las llamadas repetidas devuelven el snapshot de mensaje existente.

Detener una Sesión Nativa

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

Grupos API

Grupo	APIs
Capacidad	areActivitiesSupported, getPluginVersion
Ciclo de vida de actividad SVG	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 Getting Started para planificar el trabajo de plugin nativo, conecte con Usando @capgo/capacitor-kit-de-widget 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 Ionic Enterprise Plugin Alternatives.