@capgo/capacitor-kit-de-widget

Resumen

@capgo/capacitor-widget-kit proporciona a una aplicación Capacitor dos formas de controlar widgets y Actividades en vivo:

• plantillas de SVG de actividades: define superficies de WidgetKit como SVG, cambia marcos denominados desde toques, ejecuta temporizadores de pausa/reproducción, muta estado JSON y recopila eventos de acción en la aplicación.
• sesiones de widget nativas completas: mantiene la interfaz de usuario del widget completamente en Swift/Kotlin/Java mientras Capacitor posee estado JSON compartido y mensajes de la aplicación a la widget o de la widget a la aplicación.

Utilice plantillas de SVG cuando su widget puede ser renderizado a partir de cadenas de SVG resueltas. Utilice sesiones de widget nativas completas cuando el widget necesita una interfaz de usuario nativa personalizada pero aún tiene que iniciar, detener, sincronizar estado o pedir a la aplicación que complete trabajo asíncrono.

Demostración

Flujo de plantilla de widget

Elegir un modo

Modo	Mejor para	API principales
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 nativa 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ápido y una sesión de widget nativa completa para un widget de pantalla de inicio con un diseño de layout nativo más rico.

Capacidades de plantilla SVG

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

• frames variantes de SVG nombradas, como summary, timero details.
• frameMutations pulsar, 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 actualizar el estado JSON utilizando valores literales, plantillas, timestamps, incrementos, botones de encendido o operaciones de deshacer.
• hotspots asignar áreas de toque a identificadores de acciones.
• listTemplateEvents permite que la aplicación procese acciones originadas en widgets más tarde.

La ejecución resuelve marcadores como __CAPGO_KEEP_0__ y __CAPGO_KEEP_1__ antes de que el puente nativo devuelva una superficie para la renderización. {{state.title}}, {{timers.rest.remainingText}}Capacidades del Puente Nativo Completo {{meta.template.kind}} Título de la sección “Capacidades del Puente Nativo Completo”

Las sesiones de tipo completo-nativo son para widgets que renderizan su propia interfaz de usuario de manera nativa:

Full-Native Bridge Capabilities

• startWidgetSession creates shared state and metadata for native widget code.
• updateWidgetSession o bien reemplaza el estado y marca la sesión activa nuevamente.
• stopWidgetSession registra un estado final y marca la sesión detenida.
• sendWidgetMessage coloca en cola el trabajo de aplicación a widget o de widget a aplicación.
• acknowledgeWidgetMessages marca mensajes como recibidos.
• completeWidgetMessage almacena una respuesta o fracaso para trabajos asíncronos.

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

Público API

Metodo	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 Activity nativa.
updateTemplateActivity	Reemplazar la definición de actividad, estado o abrir URL.
endTemplateActivity	Finalizar una actividad en ejecución y opcionalmente persistir una instantánea de estado de último momento.
performTemplateAction	Ejecutar parches declarativos, mutaciones de marco, mutaciones de temporizador y registro de eventos.
getTemplateActivity	Leer una actividad de plantilla almacenada.
listTemplateActivities	Listar todas las actividades de plantilla 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 nativo completo respaldada por un estado JSON compartido.
updateWidgetSession	Unir o reemplazar el estado de sesión de widget nativo completo.
stopWidgetSession	Detener una sesión de widget nativo completo y opcionalmente persistir el estado final.
getWidgetSession	Leer una sesión de widget nativo completo.
listWidgetSessions	Listar todas las sesiones de widget nativo completo.
sendWidgetMessage	Coloque un mensaje entre la aplicación y el widget nativo code.
listWidgetMessages	Lista los mensajes de puente programados.
acknowledgeWidgetMessages	Marque los mensajes de puente como reconocidos.
completeWidgetMessage	Complete o fracase un mensaje de puente asíncrono.
getPluginVersion	Devuelve el marcador de versión de la implementación de la 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, hotspotsy metadatos.
• CapgoTemplateActionIntent conecta botones de widget iOS interactivos a acciones de plantilla.
• CapgoNativeWidgetBridge carga sesiones y mensajes de nativo completo 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.

Sigue adelante desde @capgo/capacitor-kit-de-widget

Si estás utilizando @capgo/capacitor-kit-de-widget para planificar la automatización de CI/CD, conecta con Usando @capgo/capacitor-kit-de-widget para la capacidad nativa en Usando @capgo/capacitor-kit-de-widget, Capgo Integración CI/CD para el flujo de trabajo del producto en Capgo Integración CI/CD, Capgo Compilaciones Nativas para el flujo de trabajo del producto en Capgo Compilaciones Nativas, Capgo Integraciones para el flujo de trabajo del producto en Capgo Integraciones, y Integración de CI/CD para el detalle de implementación en Integración de CI/CD.