@capgo/capacitor-widget-kit

概览

通过 Capacitor 构建 WidgetKit 和 Live Activity 界面，支持 SVG 帧、计时器、操作热区，或完全原生的 Widget 状态同步

从这里开始 areActivitiesSupported() 以及下方列出的其他核心方法。

平台支持

平台	支持	备注
iOS	是	原生
Android	是	原生
Web 端	否	使用 Capacitor.getPlatform() 做保护

Siri、快捷指令与 App Intents

Widget Kit 是 不会 一个 Siri 或 Shortcuts 桥接工具。它通过内置的类型支持 WidgetKit、ActivityKit 模板 Live Activities 以及交互式 iOS controls， LiveActivityIntent 这些类型 (CapgoTemplateActionIntent, CompleteSetIntent) 会更新存储的模板状态，并将信息追加到模板 事件日志 (event log) (listTemplateEvents / acknowledgeTemplateEvents).

它确实 不会 注册自定义快捷短语、 AppShortcutsProviderJavaScript 实体目录、Spotlight 条目或 Apple app schema。使用 @capgo/capacitor-app-intents 来实现这些功能。如需与以下工具进行完整对比，例如 expo-app-intents，请参阅 Siri、快捷指令与小组件.

演示

Widget 模板流程

选择模式

模式	最适合	核心 API
SVG 模板模式	通过 SVG 输出渲染的 Live Activities 或小组件界面	startTemplateActivity, performTemplateAction, listTemplateEvents
全原生小组件模式	需要共享状态和异步任务的原生渲染小组件	startWidgetSession, updateWidgetSession, sendWidgetMessage

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

SVG 模板功能

SVG 模板包含了构建交互式小组件界面所需的所有组件：

• frames 包含命名的 SVG 变体，例如 summary, timer，或 details.
• frameMutations 在热点操作后切换、开关或逐帧浏览。
• timerMutations 启动、暂停、恢复、切换、重置、停止或更改计时器时长。
• patches 使用字面量、模板、时间戳、增量、切换或取消设置操作来更新 JSON 状态。
• hotspots 将点击区域映射到操作标识符。
• listTemplateEvents 让应用稍后处理由 Widget 发起的操作。

运行时会解析如下占位符 {{state.title}}, {{timers.rest.remainingText}}，以及 {{meta.template.kind}} 在原生桥接返回渲染表面之前。

全原生桥接能力

全原生会话适用于自行进行原生 UI 渲染的 Widget：

• startWidgetSession 为原生 Widget code 创建共享状态和元数据。
• updateWidgetSession 合并或替换状态，并将会话重新标记为活跃。
• stopWidgetSession 记录最终状态，并将会话标记为已停止。
• sendWidgetMessage 排队处理 App 与 Widget 之间的交互任务。
• acknowledgeWidgetMessages 将消息标记为已接收。
• completeWidgetMessage 存储异步任务的响应结果或失败信息。

消息在完成后具有幂等性：重试已完成或失败的消息将返回现有结果，而不会覆盖它。

公开 API

方法	描述
areActivitiesSupported	检查当前的设备是否支持运行原生模板 Activity bridge。
startTemplateActivity	持久化一个 SVG 模板 Activity 并启动原生 Live Activity bridge。
updateTemplateActivity	替换 Activity 的定义、状态或打开的 URL。
endTemplateActivity	结束正在运行的 Activity，并可选择持久化最后一次状态快照。
performTemplateAction	执行声明式补丁 (patches)、帧变更 (frame mutations)、定时器变更 (timer mutations) 以及事件日志记录。
getTemplateActivity	读取一个已存储的模板 Activity。
listTemplateActivities	列出所有已存储的模板 Activity。
listTemplateEvents	读取由模板操作 (template actions) 发出的动作事件。
acknowledgeTemplateEvents	将模板事件标记为已处理。
startWidgetSession	启动一个由共享 JSON 状态支持的全原生 Widget 会话。
updateWidgetSession	合并或替换全原生 Widget 会话的状态。
stopWidgetSession	停止全原生 Widget 会话，并可选择持久化最终状态。
getWidgetSession	读取一个全原生 Widget 会话。
listWidgetSessions	列出所有全原生 Widget 会话。
sendWidgetMessage	在 App 与原生 Widget code 之间将消息加入队列。
listWidgetMessages	列出已排队的 Bridge 消息。
acknowledgeWidgetMessages	将 Bridge 消息标记为已确认。
completeWidgetMessage	将异步 Bridge 消息标记为完成或失败。
getPluginVersion	返回平台实现的版本标识。

原生组件

该插件还附带用于 Widget Target 的原生辅助工具：

• CapgoTemplateWidgetBridge 将 SVG 模板 surface 解析为 svg, frameId, hotspots以及元数据。
• CapgoTemplateActionIntent 将交互式 iOS widget 按钮连接到模板 action。
• CapgoNativeWidgetBridge 从原生 widget code 加载完整的原生 session 和消息。
• Android 模板助手提供匹配的 action receiver 和 widget bridge 行为。

单一事实来源

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 Build 用于 Capgo Native Builds 中的产品工作流， Capgo 集成 用于 Capgo Integrations 中的产品工作流，以及 CI/CD 集成 关于 CI/CD Integration 中的实现细节。