@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 Activity来实现快速的帧/计时器控制，并使用一个全局原生小部件会话来实现一个具有更丰富原生布局的主屏幕小部件。

SVG模板功能

SVG模板包含用于交互式小部件表面的必要组件：

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

运行时会解析像这样的占位符： {{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	Queue a message between the app and native widget code.
listWidgetMessages	列出排队的桥接消息。
acknowledgeWidgetMessages	标记桥接消息为已确认。
completeWidgetMessage	完成或失败一个异步桥接消息。
getPluginVersion	返回平台实现版本标记。

原生碎片

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

• CapgoTemplateWidgetBridge 将SVG模板表面转换为 svg, frameId, hotspots,以及元数据。
• CapgoTemplateActionIntent 将互动iOS小组件按钮连接到模板动作。
• CapgoNativeWidgetBridge 从原生小组件code加载全原生会话和消息。
• 真实数据来源

原生组件

The API reference is synced from src/definitions.ts 继续阅读@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kit

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 集成 for the product workflow in Capgo Integrations, and CI/CD 集成 了解 CI/CD 集成的实现细节。