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

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

SVG 模板功能

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

• frames 例如， summary, timer或 details.
• frameMutations 在热点动作后切换、切换、或逐帧切换。
• timerMutations 开始、暂停、恢复、切换、重置、停止或改变计时器持续时间。
• patches 使用.literal 值、模板、时间戳、增量、切换或清除操作更新 JSON 状态。
• 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	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 与其连接 使用@capgo/capacitor-widget-kit 为@capgo/capacitor-widget-kit原生能力 Capgo CI/CD 为Capgo CI/CD产品工作流 Capgo Native Builds 为Capgo Native Builds产品工作流 Capgo Integrations 为产品工作流在Capgo Integrations中,和 构建集成 了解构建集成的实现细节。