@capgo/capacitor-widget-kit

概述

@capgo/capacitor-widget-kit 为Capacitor应用提供了两种方式来驱动widget和Live Activities：

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

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

演示

小部件模板流程

选择一个模式

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

两种模式可以共存在同一个应用中。例如，一个健身应用可以使用 SVG Live Activity 进行快速的帧/计时器控制，并使用一个全局原生小部件会话来创建一个具有更丰富原生布局的主屏幕小部件。

SVG 模板功能

例如，

• frames 或 summary, timer点击热点后可以切换、切换或逐帧播放。 details.
• frameMutations 可以开始、暂停、恢复、切换、重置、停止或更改计时器持续时间。
• timerMutations 可以使用.literal 值、模板、时间戳、增量、开关或清除操作更新 JSON 状态。
• patches 可以将触摸区域映射到动作标识符。
• hotspots 让应用稍后处理小部件产生的动作。
• listTemplateEvents 运行时会解析像这样的占位符

__CAPGO_KEEP_0__ {{state.title}}, {{timers.rest.remainingText}}，和 {{meta.template.kind}} 在原生桥接返回渲染表面的前置步骤。

全原生桥接功能

全原生会话是为渲染自己的 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	返回平台实现版本标记。

原生碎片

插件还提供了原生助手来帮助widget目标：

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

真相来源

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

继续从@capgo/capacitor-widget-kit

如果您正在使用 @capgo/capacitor-widget-kit 来规划 CI/CD 自动化，连接它与 使用 @capgo/capacitor-widget-kit 来实现在使用 @capgo/capacitor-widget-kit 中的原生能力 @Capgo CI/CD 来实现产品工作流程中的 @Capgo CI/CD @Capgo 原生构建 来实现产品工作流程中的 @Capgo 原生构建 @Capgo 集成 来实现产品工作流程中的 @Capgo 集成， ["CI/CD 集成"] ["CI/CD 集成的实现细节。"]