@capgo/capacitor-小部件套件

概述

@capgo/capacitor-widget-kit 为 Capacitor 应用程序提供两种方式来驱动 widget 和 Live 活动：

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

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

演示

小部件模板流程

选择一个模式

模式	最佳用途	主要 API
SVG 模板活动	实时活动或从 SVG 输出渲染的小部件表面	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}} 在原生桥返回渲染表面的前面

全原生桥功能

创建共享状态和元数据用于原生小部件__CAPGO_KEEP_0__。

• startWidgetSession creates shared state and metadata for native widget code.
• updateWidgetSession 记录最终状态并标记会话停止。
• stopWidgetSession 排队应用程序到小部件或小部件到应用程序的工作。
• sendWidgetMessage 标记消息为已接收。
• acknowledgeWidgetMessages 全原生会话是为渲染自己的 UI 的小部件而设计的：
• completeWidgetMessage 异步任务存储响应或失败。

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

公共API

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

真实来源

此API引用是从 src/definitions.ts 在插件仓库中。

从 @capgo/capacitor-widget-kit 中继续。

如果您正在使用 @capgo/capacitor-小部件套件 来规划CI/CD自动化，连接它与 使用 @capgo/capacitor-widget-kit 来规划CI/CD自动化的本地能力在使用 @capgo/capacitor-widget-kit 中 Capgo CI/CD 规划产品工作流程在 Capgo CI/CD 中 Capgo 原生构建 规划产品工作流程在 Capgo Native Builds 中 Capgo 集成 为Capgo产品工作流程中的集成 CI/CD 集成 开始使用__CAPGO_KEEP_0__