@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 输出渲染的 Live 活动或小部件表面	startTemplateActivity, performTemplateAction, listTemplateEvents
全原生小部件会话	需要共享状态和异步作业的原生渲染小部件	startWidgetSession, updateWidgetSession, sendWidgetMessage

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

SVG模板功能

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

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

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

全原生桥功能

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

• startWidgetSession 创建共享状态和元数据的原生小部件code。
• updateWidgetSession 合并或替换状态并标记会话为激活。
• stopWidgetSession 记录最后一个状态并标记会话为停止。
• sendWidgetMessage 排队app-to-widget或widget-to-app的工作。
• 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 loads full-native sessions and messages from native widget 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 Native Builds 为Capgo Native Builds产品工作流 Capgo Integrations 为产品工作流在Capgo Integrations中， CI/CD 集成 CI/CD 集成的实现细节