@capgo/capacitor-widget-kit

Resumen

Crea superficies de WidgetKit y Live Activity desde Capacitor con marcos SVG, temporizadores, hotspots o sincronización full-native del estado del widget

Empieza con areActivitiesSupported() y los demás métodos principales detallados abajo.

Soporte de plataformas

Plataforma	Soporte	Notas
iOS	Sí	Nativo
Android	Sí	Nativo
Web	No	Protege con Capacitor.getPlatform()

Siri, Shortcuts y App Intents

WidgetKit es necesitas un puente para Siri o Shortcuts. Sí que cubre WidgetKit, Live Activities de plantilla con ActivityKit y controles interactivos de iOS mediante LiveActivityIntent types (CapgoTemplateActionIntent, CompleteSetIntent) que actualizan el estado almacenado de la plantilla y añaden al event log (listTemplateEvents / acknowledgeTemplateEvents).

Sí, lo hace necesitas register custom shortcut phrases, AppShortcutsProvider, catálogos de entidades JavaScript, elementos de Spotlight o esquemas de apps de Apple. Usa @capgo/capacitor-app-intents para ello. Para una comparativa completa con herramientas como expo-app-intents, consulta Siri, Shortcuts y widgets.

Demo

Flujo de la plantilla del widget

Elige un modo

Modo	Ideal para	APIs principales
Actividad con plantilla SVG	Live Activities o superficies de widgets que se renderizan desde un SVG	startTemplateActivity, performTemplateAction, listTemplateEvents
Sesión de widget full-native	Widgets renderizados nativamente que requieren estado compartido y tareas asíncronas	startWidgetSession, updateWidgetSession, sendWidgetMessage

Ambos modos pueden coexistir en la misma app. Por ejemplo, una app de entrenamiento puede usar una Live Activity con SVG para controles rápidos de timer y una sesión de widget full-native para un widget de la home con un layout nativo más rico.

Capacidades de la plantilla SVG

Las plantillas SVG incluyen los elementos necesarios para superficies de widgets interactivas:

• frames mantener variantes SVG con nombre como summary, timer, o details.
• frameMutations cambiar, alternar o avanzar entre frames tras una acción de hotspot.
• timerMutations iniciar, pausar, reanudar, alternar, resetear, detener o cambiar la duración del timer.
• patches actualizar el estado JSON usando valores literales, templates, timestamps, incrementos, toggles o desasignaciones.
• hotspots mapear áreas de toque a identificadores de acción.
• listTemplateEvents permite que la app procese acciones de widgets más tarde.

El runtime resuelve placeholders como {{state.title}}, {{timers.rest.remainingText}}, y {{meta.template.kind}} antes de que el native bridge devuelva una superficie para renderizar.

Capacidades completas del Native Bridge

Las sesiones full-native son para widgets que renderizan su propia UI de forma nativa:

• startWidgetSession crea el estado compartido y los metadatos para el widget nativo code.
• updateWidgetSession fusiona o reemplaza el estado y marca la sesión como activa de nuevo.
• stopWidgetSession registra un estado final y marca la sesión como detenida.
• sendWidgetMessage encola trabajo de app-to-widget o widget-to-app.
• acknowledgeWidgetMessages marca los mensajes como recibidos.
• completeWidgetMessage almacena una respuesta o un fallo para jobs asíncronos.

Los mensajes son idempotentes al completarse: reintentar un mensaje completado o fallido devuelve el resultado existente en lugar de sobrescribirlo.

Público API

Método	Descripción
areActivitiesSupported	Comprueba si el bridge de actividad de plantilla nativa puede ejecutarse en el dispositivo actual.
startTemplateActivity	Persiste una actividad de plantilla SVG e inicia el bridge nativo de Live Activity.
updateTemplateActivity	Reemplaza la definición de la actividad, el estado o la URL de apertura.
endTemplateActivity	Finaliza una actividad en ejecución y, opcionalmente, persiste un último snapshot del estado.
performTemplateAction	Ejecuta parches declarativos, mutaciones de frames, mutaciones de timers y registro de eventos.
getTemplateActivity	Lee una actividad de plantilla almacenada.
listTemplateActivities	Lista todas las actividades de plantilla almacenadas.
listTemplateEvents	Lee los eventos de acción emitidos por las acciones de la plantilla.
acknowledgeTemplateEvents	Marca los eventos de la plantilla como procesados.
startWidgetSession	Inicia una sesión de widget totalmente nativa respaldada por un estado JSON compartido.
updateWidgetSession	Fusiona o reemplaza el estado de sesión de un widget nativo completo.
stopWidgetSession	Detén una sesión de widget totalmente nativa y, opcionalmente, persiste el estado final.
getWidgetSession	Lee una sesión completa de widget nativo.
listWidgetSessions	Lista todas las sesiones de widget nativo.
sendWidgetMessage	Encola un mensaje entre la app y el widget nativo code.
listWidgetMessages	Lista los mensajes del bridge en cola.
acknowledgeWidgetMessages	Marca los mensajes del bridge como confirmados.
completeWidgetMessage	Completa o falla un mensaje de bridge asíncrono.
getPluginVersion	Devuelve la versión de la implementación de la plataforma.

Componentes nativos

El plugin también incluye helpers nativos para targets de widgets:

• CapgoTemplateWidgetBridge resuelve una superficie de plantilla SVG en svg, frameId, hotspots, y metadatos.
• CapgoTemplateActionIntent conecta botones interactivos del widget iOS con acciones de plantilla.
• CapgoNativeWidgetBridge carga sesiones y mensajes totalmente nativos desde el code del widget nativo.
• Los helpers de plantilla de Android ofrecen el mismo receiver de acciones y bridge de widget.

Fuente de verdad

La referencia de API se sincroniza desde src/definitions.ts en el repositorio del plugin.

Continúa desde @capgo/capacitor-widget-kit

Si estás usando @capgo/capacitor-widget-kit para planificar la automatización de CI/CD, conéctalo con Uso de @capgo/capacitor-widget-kit para la capacidad nativa en Using @capgo/capacitor-widget-kit, CI/CD de Capgo para el flujo de trabajo del producto en Capgo CI/CD, Native Builds de Capgo para el flujo de trabajo del producto en Capgo Native Builds, Integraciones de Capgo para el flujo de trabajo en Capgo Integrations, y Integración CI/CD para el detalle de implementación en CI/CD Integration.