@capgo/capacitor-kit de widget

Resumen

@capgo/capacitor-widget-kit da a una aplicación Capacitor dos formas de impulsar widgets y actividades en vivo:

• Actividades de plantillas SVG: defina superficies de WidgetKit como SVG, cambie marcos nombrados desde toques, ejecute temporizadores de pausa/reproducción, mutue el estado JSON y recolecte eventos de acción en la aplicación.
• Sesiones de widget nativo completo: mantenga la interfaz de usuario del widget completamente en Swift/Kotlin/Java mientras Capacitor posee el estado JSON compartido y mensajes de la aplicación a la widget o de la widget a la aplicación.

Use SVG templates when your widget can be rendered from resolved SVG strings. Use full-native sessions when the widget needs a custom native UI but still has to start, stop, sync state, or ask the app to complete async work.

Elige un Modo

Modo	Lo mejor para	Principal APIs
Actividad de plantilla SVG	Actividades en vivo o superficies de widget que se renderizan desde la salida SVG	startTemplateActivity, performTemplateAction, listTemplateEvents
Sesión de widget nativo completa	Widgets renderizados nativamente que necesitan estado compartido y tareas asíncronas	startWidgetSession, updateWidgetSession, sendWidgetMessage

Ambos modos pueden coexistir en la misma aplicación. Por ejemplo, una aplicación de entrenamiento puede utilizar una actividad en vivo SVG para controles de marco/tiempo rápidos y una sesión de widget nativo completa para un widget de pantalla de inicio con un diseño de layout nativo más rico.

Capacidades de plantilla SVG

Los modelos SVG incluyen las piezas necesarias para superficies de widget interactivas:

• frames mantenga variantes de SVG nombradas como summary, timer, o details.
• frameMutations pase, cambiar, o avanzar por marcos después de una acción de hotspot.
• timerMutations iniciar, pausar, reanudar, cambiar, resetear, detener, o cambiar la duración del temporizador.
• patches actualice el estado JSON utilizando valores literales, plantillas, timestamps, incrementos, botones o operaciones de deshacer.
• hotspots asignar áreas de toque a identificadores de acción.
• listTemplateEvents permite que la aplicación procese acciones originadas en el widget más tarde.

La ejecución resuelve sustitutos como {{state.title}}, {{timers.rest.remainingText}}, y {{meta.template.kind}} antes de que la puente nativa devuelva una superficie para renderizar.

Capacidades de Puente Nativa Completa

Las sesiones nativas son para widgets que renderizan su propia interfaz de usuario de forma nativa:

• startWidgetSession crea un estado compartido y metadatos para el widget nativo code.
• updateWidgetSession combina o reemplaza el estado y marca la sesión como activa nuevamente.
• stopWidgetSession registra un estado final y marca la sesión como detenida.
• sendWidgetMessage coloca en cola el trabajo de aplicación a widget o de widget a aplicación.
• acknowledgeWidgetMessages marca los mensajes como recibidos.
• completeWidgetMessage almacena una respuesta o un error para las tareas asíncronas.

Los mensajes son idempotentes después de la finalización: reintentar un mensaje completado o fallido devuelve el resultado existente en lugar de sobrescribirlo.

Acceso público a API

Método	Descripción
areActivitiesSupported	Verificar si la puente de actividad de plantilla nativa puede ejecutarse en el dispositivo actual.
startTemplateActivity	Persistir una plantilla de actividad SVG y iniciar la puente de actividad de Live nativa.
updateTemplateActivity	Reemplazar la definición de actividad, estado o abrir una URL.
endTemplateActivity	Finalizar una actividad en ejecución y opcionalmente persistir una instantánea de estado de la actividad.
performTemplateAction	Ejecutar parches declarativos, mutaciones de marco, mutaciones de temporizador y registro de eventos.
getTemplateActivity	Leer una plantilla de actividad almacenada.
listTemplateActivities	Listar todas las plantillas de actividad almacenadas.
listTemplateEvents	Leer eventos de acción emitidos por acciones de plantilla.
acknowledgeTemplateEvents	Marcar eventos de plantilla como procesados.
startWidgetSession	Iniciar una sesión de widget nativa completa respaldada por un estado JSON compartido.
updateWidgetSession	Unir o reemplazar el estado de sesión de widget nativa completa.
stopWidgetSession	Detener una sesión de widget nativo completa y opcionalmente persistir el estado final.
getWidgetSession	Leer una sesión de widget nativo completa.
listWidgetSessions	Listar todas las sesiones de widget nativo.
sendWidgetMessage	Colar un mensaje entre la aplicación y el widget nativo code.
listWidgetMessages	Listar mensajes de puente colados.
acknowledgeWidgetMessages	Marcar mensajes de puente como reconocidos.
completeWidgetMessage	Completar o fallar un mensaje de puente asíncrono.
getPluginVersion	Devolver el marcador de versión de la implementación de plataforma.

Piezas nativas

El plugin también envía ayudantes nativos para objetivos de widget:

• CapgoTemplateWidgetBridge resuelve una superficie de plantilla SVG en svg, frameId, hotspots, y metadatos.
• CapgoTemplateActionIntent conecta botones de widget iOS interactivos a acciones de plantilla.
• CapgoNativeWidgetBridge carga sesiones y mensajes de widget nativo completos desde el widget nativo code.
• Los ayudantes de plantilla de Android proporcionan comportamiento de receptor de acción y puente de widget coincidente.

Fuente de Verdad

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