@capgo/capacitor-widget-kit

概述

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

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

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

演示

小部件模板流程

选择 A 模式

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

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

SVG 模板功能

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

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

运行时解析类似“__CAPGO_KEEP_0__”的占位符、和“__CAPGO_KEEP_1__”等。 {{state.title}}, {{timers.rest.remainingText}}在原生桥返回渲染表面的前提下， {{meta.template.kind}} 全原生桥接功能

全原生会话是为渲染自己的UI的小部件准备的：

合并或替换状态并标记会话为激活。

• startWidgetSession creates shared state and metadata for native widget code.
• updateWidgetSession 全原生桥接功能
• stopWidgetSession 全原生会话
• sendWidgetMessage app-to-widget 或 widget-to-app 工作队列。
• acknowledgeWidgetMessages 标记消息为已接收。
• completeWidgetMessage 存储异步任务的响应或失败。

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

公共 API

方法	描述
areActivitiesSupported	检查当前设备上是否可以运行原生模板活动桥接
startTemplateActivity	持久化 SVG 模板活动并启动原生 Live Activity 桥接
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 模板助手提供匹配的动作接收器和小部件桥接行为。

真实来源

The API reference is synced from src/definitions.ts 在插件仓库中

Keep going from @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 集成的实现细节中