@capgo/capacitor-widget-kit

概述

@capgo/capacitor-widget-kit 为您的Capacitor应用提供了两种方式来驱动小部件和实时活动：

• SVG模板活动：定义WidgetKit表面作为SVG，通过点击切换命名帧，运行暂停/播放计时器，修改JSON状态，并在应用中收集动作事件。
• 全原生小部件会话：将小部件UI完全保留在Swift/Kotlin/Java中，而Capacitor则拥有共享的JSON状态和应用到小部件或小部件到应用的消息。

使用SVG模板时，当您的小部件可以从解析的SVG字符串中渲染时。使用全原生会话时，当小部件需要一个自定义的原生UI，但仍需要启动、停止、同步状态或要求应用完成异步工作时。

选择模式

模式	最佳选择	主要API
SVG模板活动	实时活动或小部件表面，渲染自 SVG 输出	startTemplateActivity, performTemplateAction, listTemplateEvents
全本地小部件会话	需要共享状态和异步作业的本地渲染小部件	startWidgetSession, updateWidgetSession, sendWidgetMessage

两种模式可以共存在同一个应用中。例如，一个健身应用可以使用 SVG 实时活动来实现快速的帧/计时器控件，并使用全本地小部件会话来实现一个具有更丰富本地布局的主屏幕小部件。

SVG 模板功能

SVG 模板包含交互式小部件表面的所需部分：

• frames 命名的 SVG 变体，如 summary, timer或 details.
• frameMutations 在热点动作后切换、切换、或逐步浏览帧
• timerMutations 开始、暂停、恢复、切换、重置、停止或更改计时器持续时间
• patches 使用.literal 值、模板、时间戳、增量、切换或清除操作更新 JSON 状态
• hotspots 将地图区域映射到动作标识符。
• listTemplateEvents 让应用程序在后台处理由小部件触发的动作。

运行时会解析像 __CAPGO_KEEP_0__ 这样的占位符。 {{state.title}}, {{timers.rest.remainingText}}在原生桥返回渲染表面之前，会解析 __CAPGO_KEEP_1__ 和 __CAPGO_KEEP_2__。 {{meta.template.kind}} 全原生桥接功能

全原生桥接功能

创建原生小部件的共享状态和元数据。

• startWidgetSession creates shared state and metadata for native widget code.
• updateWidgetSession 记录最终状态并标记会话为停止。
• stopWidgetSession 排队应用程序到小部件或小部件到应用程序的工作。
• sendWidgetMessage 全原生会话是为那些能够原生渲染 UI 的小部件而设计的：
• acknowledgeWidgetMessages 标记消息为已接收。
• completeWidgetMessage 存储异步作业的响应或失败。

消息在完成后是幂等的：重试一个完成或失败的消息会返回现有的结果，而不是覆盖它。

公共 API

方法	描述
areActivitiesSupported	检查本机模板活动桥是否可以在当前设备上运行。
startTemplateActivity	持久化 SVG 模板活动并启动本机 Live 活动桥。
updateTemplateActivity	替换活动定义、状态或打开 URL。
endTemplateActivity	结束正在运行的活动并可选地持久化最后一个状态快照。
performTemplateAction	执行声明性补丁、帧变异、计时器变异和事件日志。
getTemplateActivity	读取一个存储的模板活动。
listTemplateActivities	列出所有存储的模板活动。
listTemplateEvents	读取模板动作发出的事件。
acknowledgeTemplateEvents	标记模板事件为已处理。
startWidgetSession	启动一个由共享 JSON 状态支持的全本机小部件会话。
updateWidgetSession	合并或替换一个全本机小部件会话状态。
stopWidgetSession	停止一个全本机小部件会话并可选地持久化最终状态。
getWidgetSession	读取一个全本机小部件会话。
listWidgetSessions	列出所有全本机小部件会话。
sendWidgetMessage	Queue a message between the app and native widget code.
listWidgetMessages	列出排队的桥接消息。
acknowledgeWidgetMessages	标记桥接消息为已确认。
completeWidgetMessage	异步桥接消息完成或失败。
getPluginVersion	返回平台实现版本标记。

原生组件

该插件还提供了针对小程序目标的原生辅助函数：

• CapgoTemplateWidgetBridge 将 SVG 模板表面解析为 svg, frameId, hotspots,和元数据。
• CapgoTemplateActionIntent 将交互式 iOS 小程序按钮连接到模板动作。
• CapgoNativeWidgetBridge 从原生小程序 code 加载全原生会话和消息。
• Android 模板辅助函数提供匹配的动作接收器和小程序桥接行为。

真实数据来源

API参考是从 src/definitions.ts 在插件仓库中。