@capgo/capacitor-widget-kit

概述

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

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

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

选择一个模式

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

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

SVG模板功能

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

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

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

__CAPGO_KEEP_1__

全原生会话是为渲染自己的原生 UI 的小部件而设计的：

• startWidgetSession 创建共享状态和元数据的原生小部件 code
• updateWidgetSession 合并或替换状态并标记会话为活动
• stopWidgetSession 记录最终状态并标记会话停止
• sendWidgetMessage 排队应用程序到小部件或小部件到应用程序的工作
• acknowledgeWidgetMessages 标记消息为已接收
• completeWidgetMessage 存储异步作业的响应或失败

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

公共 API

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

原生碎片

此插件还提供了原生小部件目标的原生助手：

• CapgoTemplateWidgetBridge 解析一个 SVG 模板表面 svg, frameId, hotspots, 和元数据。
• CapgoTemplateActionIntent 连接交互式 iOS 小部件按钮到模板动作。
• CapgoNativeWidgetBridge 加载全本机会话和消息从本机小部件 code。
• Android 模板助手提供匹配动作接收器和小部件桥接行为。

真实来源

的API引用是同步自 src/definitions.ts 在插件仓库。