@capgo/capacitor-widget-kit

概述

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

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

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

演示

小部件模板流程

选择一个模式

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

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

SVG模板功能

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

• frames 包含名为的SVG变体： 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	返回平台实现版本标记。

原生碎片

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

• 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 Native Builds 为了产品工作流程在Capgo Native Builds中 Capgo Integrations 为了产品工作流程在Capgo Integrations中，和 CI/CD Integration 为了CI/CD Integration实现细节的详细信息